From dc2948d76d67ceac9595b7f86b3d5694b5c0e69d Mon Sep 17 00:00:00 2001
From: Tim Starling <tstarling@wikimedia.org>
Date: Fri, 1 Dec 2017 21:02:26 +1100
Subject: [PATCH] A few doc comment fixups

* Remove some creation dates, they are not protected by GPL
* Remove duplicate @defgroup API
* Remove @ingroup from some @file doc comments on class files. It is not
  useful to list class files alongside classes in the doxygen module menu.
  Add @ingroup to some more class files that had @ingroup on their file,
  that was probably the author's intent.
* In PackedOverlayImageGallery, use the file comment as a class comment
* Don't put @defgroup and @file in the same comment. @defgroup makes the
  whole doc comment describe the group.
* Instead of putting AnsiTermColorer in two groups, use hierarchical
  groups.

Change-Id: If54f6e0b2bc1ea6de42045885cf836ee67b8e961
---
 includes/api/ApiImport.php                    |  4 ---
 includes/api/ApiOpenSearch.php                |  5 ++--
 includes/api/ApiRsd.php                       |  2 --
 includes/api/ApiUsageException.php            |  1 -
 includes/deferred/CdnCacheUpdate.php          |  1 -
 .../gallery/PackedOverlayImageGallery.php     |  7 +++--
 includes/installer/PhpBugTests.php            |  4 ++-
 includes/jobqueue/JobSpecification.php        |  1 -
 .../aggregator/JobQueueAggregator.php         |  3 ++
 includes/libs/rdbms/database/IDatabase.php    | 11 ++++----
 .../rdbms/database/IMaintainableDatabase.php  |  1 -
 .../libs/rdbms/exception/DBExpectedError.php  |  1 -
 .../libs/rdbms/loadbalancer/LoadBalancer.php  |  1 -
 includes/specials/SpecialUploadStash.php      |  9 ++++--
 includes/upload/UploadStash.php               | 28 ++++++++++++++++++-
 languages/classes/LanguageEn.php              |  4 ++-
 languages/classes/LanguageGan.php             |  3 +-
 maintenance/term/MWTerm.php                   | 12 ++++++--
 18 files changed, 67 insertions(+), 31 deletions(-)

diff --git a/includes/api/ApiImport.php b/includes/api/ApiImport.php
index a0f0a8dbdb..822711aa02 100644
--- a/includes/api/ApiImport.php
+++ b/includes/api/ApiImport.php
@@ -1,9 +1,5 @@
 <?php
 /**
- *
- *
- * Created on Feb 4, 2009
- *
  * Copyright © 2009 Roan Kattouw "<Firstname>.<Lastname>@gmail.com"
  *
  * This program is free software; you can redistribute it and/or modify
diff --git a/includes/api/ApiOpenSearch.php b/includes/api/ApiOpenSearch.php
index 419fd140d7..416fc7f6e4 100644
--- a/includes/api/ApiOpenSearch.php
+++ b/includes/api/ApiOpenSearch.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * Created on Oct 13, 2006
- *
  * Copyright © 2006 Yuri Astrakhan "<Firstname><Lastname>@gmail.com"
  * Copyright © 2008 Brion Vibber <brion@wikimedia.org>
  * Copyright © 2014 Wikimedia Foundation and contributors
@@ -382,6 +380,9 @@ class ApiOpenSearch extends ApiBase {
 	}
 }
 
+/**
+ * @ingroup API
+ */
 class ApiOpenSearchFormatJson extends ApiFormatJson {
 	private $warningsAsError = false;
 
diff --git a/includes/api/ApiRsd.php b/includes/api/ApiRsd.php
index fdc62a8ea9..f20d1c6c8b 100644
--- a/includes/api/ApiRsd.php
+++ b/includes/api/ApiRsd.php
@@ -3,8 +3,6 @@
 /**
  * API for MediaWiki 1.17+
  *
- * Created on October 26, 2010
- *
  * Copyright © 2010 Bryan Tong Minh and Brion Vibber
  *
  * This program is free software; you can redistribute it and/or modify
diff --git a/includes/api/ApiUsageException.php b/includes/api/ApiUsageException.php
index 4196add2c3..c200dcba6f 100644
--- a/includes/api/ApiUsageException.php
+++ b/includes/api/ApiUsageException.php
@@ -16,7 +16,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @defgroup API API
  */
 
 /**
diff --git a/includes/deferred/CdnCacheUpdate.php b/includes/deferred/CdnCacheUpdate.php
index 7fafc0ebca..301c4f3b7e 100644
--- a/includes/deferred/CdnCacheUpdate.php
+++ b/includes/deferred/CdnCacheUpdate.php
@@ -18,7 +18,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Cache
  */
 
 use Wikimedia\Assert\Assert;
diff --git a/includes/gallery/PackedOverlayImageGallery.php b/includes/gallery/PackedOverlayImageGallery.php
index db8ce68b9a..0a5a457fea 100644
--- a/includes/gallery/PackedOverlayImageGallery.php
+++ b/includes/gallery/PackedOverlayImageGallery.php
@@ -1,8 +1,5 @@
 <?php
 /**
- * Packed overlay image gallery. All images adjusted to be same height and
- * image caption being placed over top of image.
- *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
@@ -21,6 +18,10 @@
  * @file
  */
 
+/**
+ * Packed overlay image gallery. All images adjusted to be same height and
+ * image caption being placed over top of image.
+ */
 class PackedOverlayImageGallery extends PackedImageGallery {
 	/**
 	 * Add the wrapper html around the thumb's caption
diff --git a/includes/installer/PhpBugTests.php b/includes/installer/PhpBugTests.php
index d412216aaa..4e1e365dbf 100644
--- a/includes/installer/PhpBugTests.php
+++ b/includes/installer/PhpBugTests.php
@@ -18,9 +18,11 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @defgroup PHPBugTests PHP known bugs tests
  */
 
+/**
+ * @defgroup PHPBugTests PHP known bugs tests
+ */
 /**
  * Test for PHP+libxml2 bug which breaks XML input subtly with certain versions.
  * Known fixed with PHP 5.2.9 + libxml2-2.7.3
diff --git a/includes/jobqueue/JobSpecification.php b/includes/jobqueue/JobSpecification.php
index d844795143..b62b83c666 100644
--- a/includes/jobqueue/JobSpecification.php
+++ b/includes/jobqueue/JobSpecification.php
@@ -18,7 +18,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup JobQueue
  */
 
 /**
diff --git a/includes/jobqueue/aggregator/JobQueueAggregator.php b/includes/jobqueue/aggregator/JobQueueAggregator.php
index f26beee4bd..433de93af7 100644
--- a/includes/jobqueue/aggregator/JobQueueAggregator.php
+++ b/includes/jobqueue/aggregator/JobQueueAggregator.php
@@ -158,6 +158,9 @@ abstract class JobQueueAggregator {
 	}
 }
 
+/**
+ * @ingroup JobQueue
+ */
 class JobQueueAggregatorNull extends JobQueueAggregator {
 	protected function doNotifyQueueEmpty( $wiki, $type ) {
 		return true;
diff --git a/includes/libs/rdbms/database/IDatabase.php b/includes/libs/rdbms/database/IDatabase.php
index 6047fb033d..85b3481fe3 100644
--- a/includes/libs/rdbms/database/IDatabase.php
+++ b/includes/libs/rdbms/database/IDatabase.php
@@ -1,10 +1,5 @@
 <?php
 /**
- * @defgroup Database Database
- *
- * This file deals with database interface functions
- * and query specifics/optimisations.
- *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
@@ -21,7 +16,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Database
  */
 namespace Wikimedia\Rdbms;
 
@@ -30,6 +24,11 @@ use RuntimeException;
 use UnexpectedValueException;
 use stdClass;
 
+/**
+ * @defgroup Database Database
+ * This group deals with database interface functions
+ * and query specifics/optimisations.
+ */
 /**
  * Basic database interface for live and lazy-loaded relation database handles
  *
diff --git a/includes/libs/rdbms/database/IMaintainableDatabase.php b/includes/libs/rdbms/database/IMaintainableDatabase.php
index fbc2774b05..66012dae43 100644
--- a/includes/libs/rdbms/database/IMaintainableDatabase.php
+++ b/includes/libs/rdbms/database/IMaintainableDatabase.php
@@ -20,7 +20,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Database
  */
 namespace Wikimedia\Rdbms;
 
diff --git a/includes/libs/rdbms/exception/DBExpectedError.php b/includes/libs/rdbms/exception/DBExpectedError.php
index cae7f3e1a6..406d82c139 100644
--- a/includes/libs/rdbms/exception/DBExpectedError.php
+++ b/includes/libs/rdbms/exception/DBExpectedError.php
@@ -16,7 +16,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Database
  */
 
 namespace Wikimedia\Rdbms;
diff --git a/includes/libs/rdbms/loadbalancer/LoadBalancer.php b/includes/libs/rdbms/loadbalancer/LoadBalancer.php
index a67e6e913d..a9eaa9974e 100644
--- a/includes/libs/rdbms/loadbalancer/LoadBalancer.php
+++ b/includes/libs/rdbms/loadbalancer/LoadBalancer.php
@@ -18,7 +18,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Database
  */
 namespace Wikimedia\Rdbms;
 
diff --git a/includes/specials/SpecialUploadStash.php b/includes/specials/SpecialUploadStash.php
index ce8b5a09a6..8cdfb87f53 100644
--- a/includes/specials/SpecialUploadStash.php
+++ b/includes/specials/SpecialUploadStash.php
@@ -18,8 +18,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup SpecialPage
- * @ingroup Upload
  */
 
 /**
@@ -31,6 +29,9 @@
  *
  * Since this is based on the user's session, in effect this creates a private temporary file area.
  * However, the URLs for the files cannot be shared.
+ *
+ * @ingroup SpecialPage
+ * @ingroup Upload
  */
 class SpecialUploadStash extends UnlistedSpecialPage {
 	// UploadStash
@@ -447,5 +448,9 @@ class SpecialUploadStash extends UnlistedSpecialPage {
 	}
 }
 
+/**
+ * @ingroup SpecialPage
+ * @ingroup Upload
+ */
 class SpecialUploadStashTooLargeException extends UploadStashException {
 }
diff --git a/includes/upload/UploadStash.php b/includes/upload/UploadStash.php
index ce087bf89c..e25b11ec23 100644
--- a/includes/upload/UploadStash.php
+++ b/includes/upload/UploadStash.php
@@ -18,7 +18,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Upload
  */
 
 /**
@@ -576,6 +575,9 @@ class UploadStash {
 	}
 }
 
+/**
+ * @ingroup Upload
+ */
 class UploadStashFile extends UnregisteredLocalFile {
 	private $fileKey;
 	private $urlName;
@@ -765,6 +767,9 @@ class UploadStashFile extends UnregisteredLocalFile {
 	}
 }
 
+/**
+ * @ingroup Upload
+ */
 class UploadStashException extends MWException implements ILocalizedException {
 	/** @var string|array|MessageSpecifier */
 	protected $messageSpec;
@@ -788,23 +793,44 @@ class UploadStashException extends MWException implements ILocalizedException {
 	}
 }
 
+/**
+ * @ingroup Upload
+ */
 class UploadStashFileNotFoundException extends UploadStashException {
 }
 
+/**
+ * @ingroup Upload
+ */
 class UploadStashBadPathException extends UploadStashException {
 }
 
+/**
+ * @ingroup Upload
+ */
 class UploadStashFileException extends UploadStashException {
 }
 
+/**
+ * @ingroup Upload
+ */
 class UploadStashZeroLengthFileException extends UploadStashException {
 }
 
+/**
+ * @ingroup Upload
+ */
 class UploadStashNotLoggedInException extends UploadStashException {
 }
 
+/**
+ * @ingroup Upload
+ */
 class UploadStashWrongOwnerException extends UploadStashException {
 }
 
+/**
+ * @ingroup Upload
+ */
 class UploadStashNoSuchKeyException extends UploadStashException {
 }
diff --git a/languages/classes/LanguageEn.php b/languages/classes/LanguageEn.php
index 1cfcd2c74e..709ce1bacf 100644
--- a/languages/classes/LanguageEn.php
+++ b/languages/classes/LanguageEn.php
@@ -18,9 +18,11 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Language
  */
 
+/**
+ * @ingroup Language
+ */
 class EnConverter extends LanguageConverter {
 	/**
 	 * Dummy methods required by base class.
diff --git a/languages/classes/LanguageGan.php b/languages/classes/LanguageGan.php
index 6d4fa0b4a8..d6f90df633 100644
--- a/languages/classes/LanguageGan.php
+++ b/languages/classes/LanguageGan.php
@@ -18,7 +18,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Language
  */
 
 /**
@@ -71,6 +70,8 @@ class GanConverter extends LanguageConverter {
 }
 
 /**
+ * Gan Chinese
+ *
  * class that handles both Traditional and Simplified Chinese
  * right now it only distinguish gan_hans, gan_hant.
  *
diff --git a/maintenance/term/MWTerm.php b/maintenance/term/MWTerm.php
index d90d06956e..ec8aeb0162 100644
--- a/maintenance/term/MWTerm.php
+++ b/maintenance/term/MWTerm.php
@@ -20,13 +20,21 @@
  *
  * @file
  * @ingroup Maintenance Testing
+ */
+
+/**
+ * @defgroup TermColorer TermColorer
+ * @ingroup Maintenance Testing
  * @todo Fixme: Make this more generic
+ *
+ * Set of classes to help with test output and such. Right now pretty specific
+ * to the parser tests but could be more useful one day :)
  */
 
 /**
  * Terminal that supports ANSI escape sequences.
  *
- * @ingroup Maintenance Testing
+ * @ingroup TermColorer
  */
 class AnsiTermColorer {
 	function __construct() {
@@ -59,7 +67,7 @@ class AnsiTermColorer {
 /**
  * A colour-less terminal
  *
- * @ingroup Maintenance Testing
+ * @ingroup TermColorer
  */
 class DummyTermColorer {
 	public function color( $color ) {
-- 
2.20.1