filerepo: Clean up file and class doc comments

* Remove copy-paste descriptions that are unrelated to the file.

* Move any useful information from file block to class block.

* Ensure any relevant `ingroup` is set on the class block.

* Remove left-over ingroup and class description from file block,
  which pollutes the doc index for no gain.

* Mark some obscure classes that have no references outside
  core in Codesearch Everywhere as internal.

Change-Id: If2360596b4a7511db7439b4b9867b0600ce2d5f8

12 files changed, 16 insertions, 37 deletions

diff --git a/includes/filerepo/file/ArchivedFile.php b/includes/filerepo/file/ArchivedFile.php
index 0118f2f04906..30e3e8074370 100644
--- a/includes/filerepo/file/ArchivedFile.php
+++ b/includes/filerepo/file/ArchivedFile.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * Deleted file in the 'filearchive' 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
@@ -18,7 +16,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup FileAbstraction
  */
 
 use MediaWiki\MediaWikiServices;
@@ -27,7 +24,7 @@ use MediaWiki\Revision\RevisionRecord;
 use MediaWiki\User\UserIdentity;
 
 /**
- * Class representing a row of the 'filearchive' table
+ * Deleted file in the 'filearchive' table.
  *
  * @stable to extend
  * @ingroup FileAbstraction
diff --git a/includes/filerepo/file/ForeignAPIFile.php b/includes/filerepo/file/ForeignAPIFile.php
index 25295e393c6f..aa5d42f1e25c 100644
--- a/includes/filerepo/file/ForeignAPIFile.php
+++ b/includes/filerepo/file/ForeignAPIFile.php
@@ -16,7 +16,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup FileAbstraction
  */
 
 use MediaWiki\MediaWikiServices;
diff --git a/includes/filerepo/file/ForeignDBFile.php b/includes/filerepo/file/ForeignDBFile.php
index 617b3cab73d2..687d68f947cd 100644
--- a/includes/filerepo/file/ForeignDBFile.php
+++ b/includes/filerepo/file/ForeignDBFile.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * Foreign file with an accessible MediaWiki database.
- *
  * 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,7 +16,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup FileAbstraction
  */
 
 use MediaWiki\MediaWikiServices;
@@ -26,7 +23,7 @@ use MediaWiki\User\UserIdentity;
 use Wikimedia\Rdbms\DBUnexpectedError;
 
 /**
- * Foreign file with an accessible MediaWiki database
+ * Foreign file from a reachable database in the same wiki farm.
  *
  * @ingroup FileAbstraction
  */
diff --git a/includes/filerepo/file/LocalFile.php b/includes/filerepo/file/LocalFile.php
index 9ca0a6a5b95e..e3f6b55bfc36 100644
--- a/includes/filerepo/file/LocalFile.php
+++ b/includes/filerepo/file/LocalFile.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * Local file in the wiki's own database.
- *
  * 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,7 +16,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup FileAbstraction
  */
 
 use MediaWiki\Deferred\LinksUpdate\LinksUpdate;
@@ -34,7 +31,7 @@ use Wikimedia\Rdbms\IDatabase;
 use Wikimedia\Rdbms\IResultWrapper;
 
 /**
- * Class to represent a local file in the wiki's own database
+ * Local file in the wiki's own database.
  *
  * Provides methods to retrieve paths (physical, logical, URL),
  * to generate image thumbnails or for uploading.
diff --git a/includes/filerepo/file/LocalFileDeleteBatch.php b/includes/filerepo/file/LocalFileDeleteBatch.php
index a3fa2835eaca..cddcec509527 100644
--- a/includes/filerepo/file/LocalFileDeleteBatch.php
+++ b/includes/filerepo/file/LocalFileDeleteBatch.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * Local file in the wiki's own database.
- *
  * 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,7 +16,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup FileAbstraction
  */
 
 use MediaWiki\MediaWikiServices;
@@ -28,6 +25,8 @@ use Wikimedia\ScopedCallback;
 
 /**
  * Helper class for file deletion
+ *
+ * @internal
  * @ingroup FileAbstraction
  */
 class LocalFileDeleteBatch {
diff --git a/includes/filerepo/file/LocalFileLockError.php b/includes/filerepo/file/LocalFileLockError.php
index e8d01547a681..64e39fb066dc 100644
--- a/includes/filerepo/file/LocalFileLockError.php
+++ b/includes/filerepo/file/LocalFileLockError.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * Local file in the wiki's own database.
- *
  * 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,12 +16,12 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup FileAbstraction
  */
 
 /**
  * @newable
  * @stable to extend
+ * @ingroup FileAbstraction
  */
 class LocalFileLockError extends ErrorPageError {
 
diff --git a/includes/filerepo/file/LocalFileMoveBatch.php b/includes/filerepo/file/LocalFileMoveBatch.php
index b66b76ae3dfc..476f95ef6cc5 100644
--- a/includes/filerepo/file/LocalFileMoveBatch.php
+++ b/includes/filerepo/file/LocalFileMoveBatch.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * Local file in the wiki's own database.
- *
  * 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,7 +16,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup FileAbstraction
  */
 
 use MediaWiki\Logger\LoggerFactory;
@@ -29,6 +26,7 @@ use Wikimedia\ScopedCallback;
 
 /**
  * Helper class for file movement
+ *
  * @ingroup FileAbstraction
  */
 class LocalFileMoveBatch {
diff --git a/includes/filerepo/file/LocalFileRestoreBatch.php b/includes/filerepo/file/LocalFileRestoreBatch.php
index c30536501a00..762593fc3d5b 100644
--- a/includes/filerepo/file/LocalFileRestoreBatch.php
+++ b/includes/filerepo/file/LocalFileRestoreBatch.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * Local file in the wiki's own database.
- *
  * 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,7 +16,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup FileAbstraction
  */
 
 use MediaWiki\MediaWikiServices;
@@ -26,6 +23,8 @@ use Wikimedia\ScopedCallback;
 
 /**
  * Helper class for file undeletion
+ *
+ * @internal
  * @ingroup FileAbstraction
  */
 class LocalFileRestoreBatch {
diff --git a/includes/filerepo/file/MediaFileTrait.php b/includes/filerepo/file/MediaFileTrait.php
index 8db25732db43..ecaf474bcaec 100644
--- a/includes/filerepo/file/MediaFileTrait.php
+++ b/includes/filerepo/file/MediaFileTrait.php
@@ -24,7 +24,8 @@ use MediaWiki\User\UserIdentity;
 
 /**
  * Trait for functionality related to media files
- * @since 1.35
+ *
+ * @internal
  * @ingroup FileRepo
  */
 trait MediaFileTrait {
diff --git a/includes/filerepo/file/MetadataStorageHelper.php b/includes/filerepo/file/MetadataStorageHelper.php
index 1c3282ae6bca..8619fc8969ae 100644
--- a/includes/filerepo/file/MetadataStorageHelper.php
+++ b/includes/filerepo/file/MetadataStorageHelper.php
@@ -16,7 +16,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup FileAbstraction
  */
 
 use MediaWiki\Logger\LoggerFactory;
diff --git a/includes/filerepo/file/OldLocalFile.php b/includes/filerepo/file/OldLocalFile.php
index 031fe4bd9a2c..38f4a31e64cb 100644
--- a/includes/filerepo/file/OldLocalFile.php
+++ b/includes/filerepo/file/OldLocalFile.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * Old file in the oldimage 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
@@ -18,7 +16,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup FileAbstraction
  */
 
 use MediaWiki\MediaWikiServices;
@@ -27,7 +24,7 @@ use MediaWiki\Revision\RevisionRecord;
 use MediaWiki\User\UserIdentity;
 
 /**
- * Class to represent a file in the oldimage table
+ * Old file in the oldimage table.
  *
  * @stable to extend
  * @ingroup FileAbstraction
diff --git a/includes/filerepo/file/UnregisteredLocalFile.php b/includes/filerepo/file/UnregisteredLocalFile.php
index 2f677fe75329..4a104d01d16a 100644
--- a/includes/filerepo/file/UnregisteredLocalFile.php
+++ b/includes/filerepo/file/UnregisteredLocalFile.php
@@ -1,8 +1,5 @@
 <?php
-
 /**
- * File without associated database record.
- *
  * 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
@@ -19,14 +16,15 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup FileAbstraction
  */
 
 use MediaWiki\MediaWikiServices;
 
 /**
- * A file object referring to either a standalone local file, or a file in a
- * local repository with no database, for example an FileRepo repository.
+ * File without associated database record.
+ *
+ * Represents a standalone local file, or a file in a local repository
+ * with no database, for example a FileRepo repository.
  *
  * Read-only.
  *