Storage: Minor docs and file header cleanup

* Move description and ingroup annotations from PHP file docblock to
  class docblock, where IDEs and Doxygen (and humans!) tend to read it
  from.

  This is in part evidences by the fact that for numerous classes,
  the file docblock was copy-pasted and actually about a different
  class.

  Follows-up Ia3b9b8c22 (page), I301f471f86 (language),
  I216d85c6df (PageEditStash), and others that apply similar doc
  improvements.

* Add missing `@defgroup` for page. Without this, the group is ignored
  and not added in the sidebar at
  <https://doc.wikimedia.org/mediawiki-core/master/php/>

* Clean up the file header, similar to other commits under
  <https://gerrit.wikimedia.org/r/q/message:ingroup+owner:Krinkle>.

Change-Id: I94de8299c184fee8c05b7108448255fcf36f8260

25 files changed, 26 insertions, 52 deletions

diff --git a/includes/Rest/Handler/HtmlInputTransformHelper.php b/includes/Rest/Handler/HtmlInputTransformHelper.php
index d1f871f1a798..b425c621078d 100644
--- a/includes/Rest/Handler/HtmlInputTransformHelper.php
+++ b/includes/Rest/Handler/HtmlInputTransformHelper.php
@@ -1,5 +1,4 @@
 <?php
-
 /**
  * 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
@@ -17,7 +16,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Page
  */
 namespace MediaWiki\Rest\Handler;
 
diff --git a/includes/Rest/Handler/HtmlOutputRendererHelper.php b/includes/Rest/Handler/HtmlOutputRendererHelper.php
index e7c4b940d31b..0dcc4e7c403d 100644
--- a/includes/Rest/Handler/HtmlOutputRendererHelper.php
+++ b/includes/Rest/Handler/HtmlOutputRendererHelper.php
@@ -1,5 +1,4 @@
 <?php
-
 /**
  * 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
@@ -17,7 +16,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Page
  */
 namespace MediaWiki\Rest\Handler;
 
diff --git a/includes/Revision/RevisionStore.php b/includes/Revision/RevisionStore.php
index db5ee7288cac..12fbeff7c3e5 100644
--- a/includes/Revision/RevisionStore.php
+++ b/includes/Revision/RevisionStore.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * Service for looking up page revisions.
- *
  * 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
diff --git a/includes/Storage/BlobAccessException.php b/includes/Storage/BlobAccessException.php
index 82c28dd21c56..02d532ab6bf8 100644
--- a/includes/Storage/BlobAccessException.php
+++ b/includes/Storage/BlobAccessException.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * Exception representing a failure to look up a revision.
- *
  * 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
diff --git a/includes/Storage/BlobStore.php b/includes/Storage/BlobStore.php
index 2959468302e7..41ed558bd8ca 100644
--- a/includes/Storage/BlobStore.php
+++ b/includes/Storage/BlobStore.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * Service for loading and storing data blobs.
- *
  * 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
diff --git a/includes/Storage/DerivedPageDataUpdater.php b/includes/Storage/DerivedPageDataUpdater.php
index dbe3c1350c26..7ed143fab2d7 100644
--- a/includes/Storage/DerivedPageDataUpdater.php
+++ b/includes/Storage/DerivedPageDataUpdater.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * A handle for managing updates for derived page data on edit, import, purge, etc.
- *
  * 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
@@ -96,13 +94,12 @@ use WikiPage;
  * require prepareContent or prepareUpdate to have been called first, to initialize the
  * DerivedPageDataUpdater.
  *
- * @see docs/pageupdater.md for more information.
- *
  * MCR migration note: this replaces the relevant methods in WikiPage, and covers the use cases
  * of PreparedEdit.
  *
- * @internal
+ * @see docs/pageupdater.md for more information.
  *
+ * @internal
  * @since 1.32
  * @ingroup Page
  */
diff --git a/includes/Storage/EditResult.php b/includes/Storage/EditResult.php
index ce6f4b9dbf91..3b33fc0e3499 100644
--- a/includes/Storage/EditResult.php
+++ b/includes/Storage/EditResult.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * Object for storing information about the effects of an edit.
- *
  * 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
@@ -18,8 +16,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- *
- * @author Ostrzyciel
  */
 
 namespace MediaWiki\Storage;
@@ -34,6 +30,7 @@ use JsonSerializable;
  * information about whether the edit was a revert and which edits were reverted.
  *
  * @since 1.35
+ * @author Ostrzyciel
  */
 class EditResult implements JsonSerializable {
 
diff --git a/includes/Storage/EditResultBuilder.php b/includes/Storage/EditResultBuilder.php
index 015bb6518337..ebb2c4e3ac4e 100644
--- a/includes/Storage/EditResultBuilder.php
+++ b/includes/Storage/EditResultBuilder.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * Builder class for the EditResult object.
- *
  * 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
@@ -18,8 +16,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- *
- * @author Ostrzyciel
  */
 
 namespace MediaWiki\Storage;
@@ -35,6 +31,7 @@ use Wikimedia\Assert\Assert;
  *
  * @internal Only for use by PageUpdater
  * @since 1.35
+ * @author Ostrzyciel
  */
 class EditResultBuilder {
 
diff --git a/includes/Storage/EditResultCache.php b/includes/Storage/EditResultCache.php
index 08e163656527..589f48e12075 100644
--- a/includes/Storage/EditResultCache.php
+++ b/includes/Storage/EditResultCache.php
@@ -16,8 +16,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- *
- * @author Ostrzyciel
  */
 
 namespace MediaWiki\Storage;
@@ -36,9 +34,9 @@ use Wikimedia\Rdbms\ILoadBalancer;
  * asked to retrieve an EditResult for an edit and the requested key is not present in the
  * main stash, the class will attempt to retrieve the EditResult from revert tags.
  *
- * @since 1.36
- *
  * @internal Used by RevertedTagUpdateManager
+ * @since 1.36
+ * @author Ostrzyciel
  */
 class EditResultCache {
 
diff --git a/includes/Storage/NameTableAccessException.php b/includes/Storage/NameTableAccessException.php
index 9c44346fbc71..7a49912013c3 100644
--- a/includes/Storage/NameTableAccessException.php
+++ b/includes/Storage/NameTableAccessException.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * Exception representing a failure to look up a row from a name table.
- *
  * 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
diff --git a/includes/Storage/NameTableStore.php b/includes/Storage/NameTableStore.php
index 0d09d7d10a46..b29a45ec1685 100644
--- a/includes/Storage/NameTableStore.php
+++ b/includes/Storage/NameTableStore.php
@@ -31,8 +31,8 @@ use Wikimedia\Rdbms\ILoadBalancer;
 use Wikimedia\RequestTimeout\TimeoutException;
 
 /**
- * @author Addshore
  * @since 1.31
+ * @author Addshore
  */
 class NameTableStore {
 
diff --git a/includes/Storage/NameTableStoreFactory.php b/includes/Storage/NameTableStoreFactory.php
index 90216863a8d9..ddf659b7e064 100644
--- a/includes/Storage/NameTableStoreFactory.php
+++ b/includes/Storage/NameTableStoreFactory.php
@@ -14,6 +14,7 @@
  * with this program; if not, write to the Free Software Foundation, Inc.,
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
+ *
  * @file
  */
 
diff --git a/includes/Storage/PageEditStash.php b/includes/Storage/PageEditStash.php
index e8f89252f9ec..764483b1a979 100644
--- a/includes/Storage/PageEditStash.php
+++ b/includes/Storage/PageEditStash.php
@@ -49,6 +49,7 @@ use WikiPage;
  * See also mediawiki.action.edit/stash.js.
  *
  * @since 1.34
+ * @ingroup Page
  */
 class PageEditStash {
 	/** @var BagOStuff */
diff --git a/includes/Storage/PageUpdateException.php b/includes/Storage/PageUpdateException.php
index 383a9c106551..68256d01621b 100644
--- a/includes/Storage/PageUpdateException.php
+++ b/includes/Storage/PageUpdateException.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * Exception representing a failure to update a page entry.
- *
  * 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
diff --git a/includes/Storage/PageUpdater.php b/includes/Storage/PageUpdater.php
index 7461974b77b5..96c71e190d78 100644
--- a/includes/Storage/PageUpdater.php
+++ b/includes/Storage/PageUpdater.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * Controller-like object for creating and updating pages by creating new revisions.
- *
  * 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
@@ -18,8 +16,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- *
- * @author Daniel Kinzler
  */
 
 namespace MediaWiki\Storage;
@@ -72,12 +68,13 @@ use WikiPage;
  * This allows application logic to safely perform edit conflict resolution using the parent
  * revision's content.
  *
- * @see docs/pageupdater.md for more information.
- *
  * MCR migration note: this replaces the relevant methods in WikiPage.
  *
+ * @see docs/pageupdater.md for more information.
+ *
  * @since 1.32
  * @ingroup Page
+ * @author Daniel Kinzler
  * @phan-file-suppress PhanTypeArraySuspiciousNullable Cannot read type of $this->status->value
  */
 class PageUpdater {
diff --git a/includes/Storage/PageUpdaterFactory.php b/includes/Storage/PageUpdaterFactory.php
index 25629c588ab3..82dec7dfa551 100644
--- a/includes/Storage/PageUpdaterFactory.php
+++ b/includes/Storage/PageUpdaterFactory.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * A factory for DerivedPageDataUpdater instances.
- *
  * 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
@@ -50,7 +48,7 @@ use Wikimedia\Rdbms\ILBFactory;
 use WikiPage;
 
 /**
- * A factory for PageUpdater instances.
+ * A factory for PageUpdater and DerivedPageDataUpdater instances.
  *
  * @since 1.37
  * @ingroup Page
diff --git a/includes/Storage/RevertedTagUpdate.php b/includes/Storage/RevertedTagUpdate.php
index 137682304724..0d5bb4dcd323 100644
--- a/includes/Storage/RevertedTagUpdate.php
+++ b/includes/Storage/RevertedTagUpdate.php
@@ -16,8 +16,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- *
- * @author Ostrzyciel
  */
 
 namespace MediaWiki\Storage;
@@ -38,6 +36,7 @@ use Wikimedia\Rdbms\ILoadBalancer;
  * This class is used by RevertedTagUpdateJob to perform the actual update.
  *
  * @since 1.36
+ * @author Ostrzyciel
  */
 class RevertedTagUpdate implements DeferrableUpdate {
 
diff --git a/includes/Storage/RevertedTagUpdateManager.php b/includes/Storage/RevertedTagUpdateManager.php
index 842dcd5d0819..860c7c110df4 100644
--- a/includes/Storage/RevertedTagUpdateManager.php
+++ b/includes/Storage/RevertedTagUpdateManager.php
@@ -16,8 +16,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- *
- * @author Ostrzyciel
  */
 
 namespace MediaWiki\Storage;
@@ -32,6 +30,7 @@ use RevertedTagUpdateJob;
  * management extensions.
  *
  * @since 1.36
+ * @author Ostrzyciel
  */
 class RevertedTagUpdateManager {
 
diff --git a/includes/Storage/RevisionSlotsUpdate.php b/includes/Storage/RevisionSlotsUpdate.php
index a4643dd1ae89..8c632f05c8d4 100644
--- a/includes/Storage/RevisionSlotsUpdate.php
+++ b/includes/Storage/RevisionSlotsUpdate.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * Value object representing a modification of revision slots.
- *
  * 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
diff --git a/includes/Storage/SqlBlobStore.php b/includes/Storage/SqlBlobStore.php
index 1b433643de09..a7c85618d457 100644
--- a/includes/Storage/SqlBlobStore.php
+++ b/includes/Storage/SqlBlobStore.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * Service for storing and loading data blobs representing revision content.
- *
  * 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
@@ -43,7 +41,7 @@ use Wikimedia\Rdbms\ILoadBalancer;
 use Wikimedia\Rdbms\IResultWrapper;
 
 /**
- * Service for storing and loading Content objects.
+ * Service for storing and loading Content objects representing revision data blobs.
  *
  * @since 1.31
  *
diff --git a/includes/page/PageIdentity.php b/includes/page/PageIdentity.php
index 2e25134bed2a..9851f4d34398 100644
--- a/includes/page/PageIdentity.php
+++ b/includes/page/PageIdentity.php
@@ -58,8 +58,8 @@ use Wikimedia\Assert\PreconditionException;
  *   another wiki.
  *
  * @stable to type
- *
  * @since 1.36
+ * @ingroup Page
  */
 interface PageIdentity extends PageReference {
 
diff --git a/includes/page/PageLookup.php b/includes/page/PageLookup.php
index bfcac20a5df3..0ee386b60b73 100644
--- a/includes/page/PageLookup.php
+++ b/includes/page/PageLookup.php
@@ -12,6 +12,7 @@ use MediaWiki\Linker\LinkTarget;
  * Default implementation is PageStore.
  *
  * @since 1.36
+ * @ingroup Page
  */
 interface PageLookup extends IDBAccessObject {
 
diff --git a/includes/page/PageRecord.php b/includes/page/PageRecord.php
index 7117033b7a6d..05efe2e672ad 100644
--- a/includes/page/PageRecord.php
+++ b/includes/page/PageRecord.php
@@ -19,6 +19,7 @@ namespace MediaWiki\Page;
  *
  * @stable to type
  * @since 1.36
+ * @ingroup Page
  */
 interface PageRecord extends ProperPageIdentity {
 
diff --git a/includes/page/PageReference.php b/includes/page/PageReference.php
index e8d05555454b..ad494198f84b 100644
--- a/includes/page/PageReference.php
+++ b/includes/page/PageReference.php
@@ -43,8 +43,8 @@ use MediaWiki\DAO\WikiAwareEntity;
  *   another wiki.
  *
  * @stable to type
- *
  * @since 1.37
+ * @ingroup Page
  */
 interface PageReference extends WikiAwareEntity {
 
diff --git a/includes/page/WikiPage.php b/includes/page/WikiPage.php
index 86213ab5e078..6541127ac81e 100644
--- a/includes/page/WikiPage.php
+++ b/includes/page/WikiPage.php
@@ -54,10 +54,16 @@ use Wikimedia\Rdbms\ILoadBalancer;
 use Wikimedia\RequestTimeout\TimeoutException;
 
 /**
+ * @defgroup Page Page
+ */
+
+/**
  * Base representation for an editable wiki page.
  *
  * Some fields are public only for backwards-compatibility. Use accessor methods.
  * In the past, this class was part of Article.php and everything was public.
+ *
+ * @ingroup Page
  */
 class WikiPage implements Page, IDBAccessObject, PageRecord {
 	use NonSerializableTrait;