mail: Improve docs, fix file headers, widen `@covers`

* Add missing `ingroup` to class blocks (and remove from any file blocks)
  as otherwise the file is indexed twice (e.g. in Doxygen) which makes
  navigation on doc.wikimedia.org rather messy.

  Remove duplicate descriptions from file blocks in favour of class
  doc blocks. This reduces needless duplication and was often
  incorrect or outdated, and helps make file headers more consistently
  (visually) ignorable.

  Ref https://gerrit.wikimedia.org/r/q/message:ingroup+is:merged

* Widen `@covers` tags in phpunit tests

  Given all called methods are de-facto and liberally claimed, and
  that we keep the coverage limited to the subject class, it maintains
  the spirit and intent by listing the class explicitly instead.

  PHPUnit offers a more precise tool when you need it (i.e. when testing
  legacy monster/god classes), but for well-written code, the
  class-wide tag is exactly what you want.

  We lose useful coverage and waste valuable time on keeping tags
  accurate through refactors (or worse, forget to do so).
  Tracking tiny per-method details wastes time in realizing (and
  fixing) when people inevitably don't keep them in sync, and time
  lost in finding uncovered code to write tests to realize it was
  already covered but "not yet claimed".

  Ref https://gerrit.wikimedia.org/r/q/owner:Krinkle+is:merged+message:Widen

While at it, improve purposes and explainations of several mail-related
classes, and set `@since`:

- EmailNotification introduced in r22110 (1.11.0), git a6f6e04841,
  later moved to a separate file in bf8810d6bc (Ic435bbdbb6).

- MailAddress introduced in r12082 (1.6.0, 1.5.7), git 5cfddf9a82.

- UserMailer converted to class with ::send in r26357 (1.12.0),
  git 353f203ce2.

Change-Id: I1216781240bcfabdebf109cef8f995355db0f659

1 files changed, 4 insertions, 9 deletions

diff --git a/tests/phpunit/includes/mail/MailAddressTest.php b/tests/phpunit/includes/mail/MailAddressTest.php
index c966819eada4..bcfe80d929ab 100644
--- a/tests/phpunit/includes/mail/MailAddressTest.php
+++ b/tests/phpunit/includes/mail/MailAddressTest.php
@@ -3,12 +3,12 @@
 use MediaWiki\User\User;
 use MediaWiki\User\UserIdentityValue;
 
+/**
+ * @group Mail
+ * @covers \MailAddress
+ */
 class MailAddressTest extends MediaWikiIntegrationTestCase {
 
-	/**
-	 * @covers \MailAddress::__construct
-	 * @covers \MailAddress::newFromUser
-	 */
 	public function testNewFromUser() {
 		if ( wfIsWindows() ) {
 			$this->markTestSkipped( 'This test only works on non-Windows platforms' );
@@ -33,7 +33,6 @@ class MailAddressTest extends MediaWikiIntegrationTestCase {
 	}
 
 	/**
-	 * @covers \MailAddress::equals
 	 * @dataProvider provideEquals
 	 */
 	public function testEquals( MailAddress $first, MailAddress $second, bool $expected ) {
@@ -50,7 +49,6 @@ class MailAddressTest extends MediaWikiIntegrationTestCase {
 	}
 
 	/**
-	 * @covers \MailAddress::toString
 	 * @dataProvider provideToString
 	 */
 	public function testToString( $useRealName, $address, $name, $realName, $expected ) {
@@ -84,9 +82,6 @@ class MailAddressTest extends MediaWikiIntegrationTestCase {
 		];
 	}
 
-	/**
-	 * @covers \MailAddress::__toString
-	 */
 	public function test__ToString() {
 		$ma = new MailAddress( 'some@email.com', 'UserName', 'A real name' );
 		$this->assertEquals( $ma->toString(), (string)$ma );