A few doc comment fixups
authorTim Starling <tstarling@wikimedia.org>
Fri, 1 Dec 2017 10:02:26 +0000 (21:02 +1100)
committerTim Starling <tstarling@wikimedia.org>
Mon, 4 Dec 2017 00:11:52 +0000 (11:11 +1100)
* 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

18 files changed:
includes/api/ApiImport.php
includes/api/ApiOpenSearch.php
includes/api/ApiRsd.php
includes/api/ApiUsageException.php
includes/deferred/CdnCacheUpdate.php
includes/gallery/PackedOverlayImageGallery.php
includes/installer/PhpBugTests.php
includes/jobqueue/JobSpecification.php
includes/jobqueue/aggregator/JobQueueAggregator.php
includes/libs/rdbms/database/IDatabase.php
includes/libs/rdbms/database/IMaintainableDatabase.php
includes/libs/rdbms/exception/DBExpectedError.php
includes/libs/rdbms/loadbalancer/LoadBalancer.php
includes/specials/SpecialUploadStash.php
includes/upload/UploadStash.php
languages/classes/LanguageEn.php
languages/classes/LanguageGan.php
maintenance/term/MWTerm.php

index a0f0a8d..822711a 100644 (file)
@@ -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
index 419fd14..416fc7f 100644 (file)
@@ -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;
 
index fdc62a8..f20d1c6 100644 (file)
@@ -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
index 4196add..c200dcb 100644 (file)
@@ -16,7 +16,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @defgroup API API
  */
 
 /**
index 7fafc0e..301c4f3 100644 (file)
@@ -18,7 +18,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Cache
  */
 
 use Wikimedia\Assert\Assert;
index db8ce68..0a5a457 100644 (file)
@@ -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
  * @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
index d412216..4e1e365 100644 (file)
  * 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
index d844795..b62b83c 100644 (file)
@@ -18,7 +18,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup JobQueue
  */
 
 /**
index f26beee..433de93 100644 (file)
@@ -158,6 +158,9 @@ abstract class JobQueueAggregator {
        }
 }
 
+/**
+ * @ingroup JobQueue
+ */
 class JobQueueAggregatorNull extends JobQueueAggregator {
        protected function doNotifyQueueEmpty( $wiki, $type ) {
                return true;
index 6047fb0..85b3481 100644 (file)
@@ -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
  *
index fbc2774..66012da 100644 (file)
@@ -20,7 +20,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Database
  */
 namespace Wikimedia\Rdbms;
 
index cae7f3e..406d82c 100644 (file)
@@ -16,7 +16,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Database
  */
 
 namespace Wikimedia\Rdbms;
index a67e6e9..a9eaa99 100644 (file)
@@ -18,7 +18,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Database
  */
 namespace Wikimedia\Rdbms;
 
index ce8b5a0..8cdfb87 100644 (file)
@@ -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 {
 }
index ce087bf..e25b11e 100644 (file)
@@ -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 {
 }
index 1cfcd2c..709ce1b 100644 (file)
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Language
  */
 
+/**
+ * @ingroup Language
+ */
 class EnConverter extends LanguageConverter {
        /**
         * Dummy methods required by base class.
index 6d4fa0b..d6f90df 100644 (file)
@@ -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.
  *
index d90d069..ec8aeb0 100644 (file)
  *
  * @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 ) {