From 394c8b52341573a8b1d1c543d52285a2ba50adef Mon Sep 17 00:00:00 2001
From: Antoine Musso <hashar@users.mediawiki.org>
Date: Wed, 8 Feb 2012 15:51:16 +0000
Subject: [PATCH] enhance filerepo doc structure

---
 includes/filerepo/FileRepo.php                    |  8 ++++++++
 includes/filerepo/RepoGroup.php                   |  4 ----
 includes/filerepo/backend/FileBackend.php         | 15 ++++++++++++---
 .../backend/lockmanager/LSLockManager.php         |  2 ++
 .../filerepo/backend/lockmanager/LockManager.php  | 12 ++++++++++--
 includes/filerepo/file/ArchivedFile.php           |  4 ++--
 includes/filerepo/file/File.php                   | 11 +++++++++--
 includes/filerepo/file/ForeignAPIFile.php         |  4 ++--
 includes/filerepo/file/ForeignDBFile.php          |  4 ++--
 includes/filerepo/file/LocalFile.php              | 10 +++++-----
 includes/filerepo/file/OldLocalFile.php           |  4 ++--
 includes/filerepo/file/UnregisteredLocalFile.php  |  4 ++--
 12 files changed, 56 insertions(+), 26 deletions(-)

diff --git a/includes/filerepo/FileRepo.php b/includes/filerepo/FileRepo.php
index 203a956305..1ccbd46c26 100644
--- a/includes/filerepo/FileRepo.php
+++ b/includes/filerepo/FileRepo.php
@@ -1,4 +1,12 @@
 <?php
+/**
+ * @defgroup FileRepo File Repository
+ *
+ * @brief This module handles how MediaWiki interacts with filesystems.
+ *
+ * @details
+ */
+
 /**
  * Base code for file repositories.
  *
diff --git a/includes/filerepo/RepoGroup.php b/includes/filerepo/RepoGroup.php
index da6c7d9f30..334ef2b818 100644
--- a/includes/filerepo/RepoGroup.php
+++ b/includes/filerepo/RepoGroup.php
@@ -6,10 +6,6 @@
  * @ingroup FileRepo
  */
 
-/**
- * @defgroup FileRepo FileRepo
- */
-
 /**
  * Prioritized list of file repositories
  *
diff --git a/includes/filerepo/backend/FileBackend.php b/includes/filerepo/backend/FileBackend.php
index b4b9ea244b..1d699e5555 100644
--- a/includes/filerepo/backend/FileBackend.php
+++ b/includes/filerepo/backend/FileBackend.php
@@ -1,4 +1,11 @@
 <?php
+/**
+ * @defgroup FileBackend File backend
+ * @ingroup  FileRepo
+ *
+ * This module regroup classes meant for MediaWiki to interacts with
+ */
+
 /**
  * @file
  * @ingroup FileBackend
@@ -7,6 +14,7 @@
 
 /**
  * Base class for all file backend classes (including multi-write backends).
+ *
  * This class defines the methods as abstract that subclasses must implement.
  * Outside callers can assume that all backends will have these functions.
  * 
@@ -698,7 +706,8 @@ abstract class FileBackend {
 }
 
 /**
- * Base class for all backends associated with a particular storage medium.
+ * @brief Base class for all backends associated with a particular storage medium.
+ *
  * This class defines the methods as abstract that subclasses must implement.
  * Outside callers should *not* use functions with "Internal" in the name.
  * 
@@ -1255,7 +1264,7 @@ abstract class FileBackendStore extends FileBackend {
 	}
 
 	/**
-	 * @see FileBackend::getFileList()
+	 * @copydoc FileBackend::getFileList() 
 	 */
 	final public function getFileList( array $params ) {
 		list( $fullCont, $dir, $shard ) = $this->resolveStoragePath( $params['dir'] );
@@ -1625,7 +1634,7 @@ abstract class FileBackendStore extends FileBackend {
  * FileBackendStore helper function to handle file listings that span container shards.
  * Do not use this class from places outside of FileBackendStore.
  *
- * @ingroup FileBackendStore
+ * @ingroup FileBackend
  */
 class FileBackendStoreShardListIterator implements Iterator {
 	/* @var FileBackendStore */
diff --git a/includes/filerepo/backend/lockmanager/LSLockManager.php b/includes/filerepo/backend/lockmanager/LSLockManager.php
index 8b59009619..b7ac743cf0 100644
--- a/includes/filerepo/backend/lockmanager/LSLockManager.php
+++ b/includes/filerepo/backend/lockmanager/LSLockManager.php
@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * Manage locks using a lock daemon server.
+ *
  * Version of LockManager based on using lock daemon servers.
  * This is meant for multi-wiki systems that may share files.
  * All locks are non-blocking, which avoids deadlocks.
diff --git a/includes/filerepo/backend/lockmanager/LockManager.php b/includes/filerepo/backend/lockmanager/LockManager.php
index bb3260e6f0..23603a4f94 100644
--- a/includes/filerepo/backend/lockmanager/LockManager.php
+++ b/includes/filerepo/backend/lockmanager/LockManager.php
@@ -1,4 +1,9 @@
 <?php
+/**
+ * @defgroup LockManager Lock management
+ * @ingroup FileBackend
+ */
+
 /**
  * @file
  * @ingroup LockManager
@@ -7,13 +12,14 @@
 
 /**
  * Class for handling resource locking.
+ *
  * Locks on resource keys can either be shared or exclusive.
- * 
+ *
  * Implementations must keep track of what is locked by this proccess
  * in-memory and support nested locking calls (using reference counting).
  * At least LOCK_UW and LOCK_EX must be implemented. LOCK_SH can be a no-op.
  * Locks should either be non-blocking or have low wait timeouts.
- * 
+ *
  * Subclasses should avoid throwing exceptions at all costs.
  *
  * @ingroup LockManager
@@ -94,6 +100,8 @@ abstract class LockManager {
 }
 
 /**
+ * Self releasing locks
+ *
  * LockManager helper class to handle scoped locks, which
  * release when an object is destroyed or goes out of scope.
  *
diff --git a/includes/filerepo/file/ArchivedFile.php b/includes/filerepo/file/ArchivedFile.php
index 34044ba174..3b9bd7f0c2 100644
--- a/includes/filerepo/file/ArchivedFile.php
+++ b/includes/filerepo/file/ArchivedFile.php
@@ -3,13 +3,13 @@
  * Deleted file in the 'filearchive' table
  *
  * @file
- * @ingroup FileRepo
+ * @ingroup FileAbstraction
  */
 
 /**
  * Class representing a row of the 'filearchive' table
  *
- * @ingroup FileRepo
+ * @ingroup FileAbstraction
  */
 class ArchivedFile {
 	/**#@+
diff --git a/includes/filerepo/file/File.php b/includes/filerepo/file/File.php
index 6b2d673749..f74fb678f1 100644
--- a/includes/filerepo/file/File.php
+++ b/includes/filerepo/file/File.php
@@ -1,9 +1,16 @@
 <?php
+/**
+ * @defgroup FileAbstraction File abstraction
+ * @ingroup FileRepo
+ *
+ * Represents files in a repository.
+ */
+
 /**
  * Base code for files.
  *
  * @file
- * @ingroup FileRepo
+ * @ingroup FileAbstraction
  */
 
 /**
@@ -23,7 +30,7 @@
  * The convenience functions wfLocalFile() and wfFindFile() should be sufficient
  * in most cases.
  *
- * @ingroup FileRepo
+ * @ingroup FileAbstraction
  */
 abstract class File {
 	const DELETED_FILE = 1;
diff --git a/includes/filerepo/file/ForeignAPIFile.php b/includes/filerepo/file/ForeignAPIFile.php
index 0e71075599..af45e2d8c6 100644
--- a/includes/filerepo/file/ForeignAPIFile.php
+++ b/includes/filerepo/file/ForeignAPIFile.php
@@ -3,14 +3,14 @@
  * Foreign file accessible through api.php requests.
  *
  * @file
- * @ingroup FileRepo
+ * @ingroup FileAbstraction
  */
 
 /**
  * Foreign file accessible through api.php requests.
  * Very hacky and inefficient, do not use :D
  *
- * @ingroup FileRepo
+ * @ingroup FileAbstraction
  */
 class ForeignAPIFile extends File {
 	private $mExists;
diff --git a/includes/filerepo/file/ForeignDBFile.php b/includes/filerepo/file/ForeignDBFile.php
index 09bee39c0a..191a712de8 100644
--- a/includes/filerepo/file/ForeignDBFile.php
+++ b/includes/filerepo/file/ForeignDBFile.php
@@ -3,13 +3,13 @@
  * Foreign file with an accessible MediaWiki database
  *
  * @file
- * @ingroup FileRepo
+ * @ingroup FileAbstraction
  */
 
 /**
  * Foreign file with an accessible MediaWiki database
  *
- * @ingroup FileRepo
+ * @ingroup FileAbstraction
  */
 class ForeignDBFile extends LocalFile {
 
diff --git a/includes/filerepo/file/LocalFile.php b/includes/filerepo/file/LocalFile.php
index 672b224700..4c4e161743 100644
--- a/includes/filerepo/file/LocalFile.php
+++ b/includes/filerepo/file/LocalFile.php
@@ -3,7 +3,7 @@
  * Local file in the wiki's own database
  *
  * @file
- * @ingroup FileRepo
+ * @ingroup FileAbstraction
  */
 
 /**
@@ -26,7 +26,7 @@ define( 'MW_FILE_VERSION', 8 );
  * The convenience functions wfLocalFile() and wfFindFile() should be sufficient
  * in most cases.
  *
- * @ingroup FileRepo
+ * @ingroup FileAbstraction
  */
 class LocalFile extends File {
 	/**#@+
@@ -1432,7 +1432,7 @@ class LocalFile extends File {
 
 /**
  * Helper class for file deletion
- * @ingroup FileRepo
+ * @ingroup FileAbstraction
  */
 class LocalFileDeleteBatch {
 
@@ -1749,7 +1749,7 @@ class LocalFileDeleteBatch {
 
 /**
  * Helper class for file undeletion
- * @ingroup FileRepo
+ * @ingroup FileAbstraction
  */
 class LocalFileRestoreBatch {
 	/**
@@ -2097,7 +2097,7 @@ class LocalFileRestoreBatch {
 
 /**
  * Helper class for file movement
- * @ingroup FileRepo
+ * @ingroup FileAbstraction
  */
 class LocalFileMoveBatch {
 
diff --git a/includes/filerepo/file/OldLocalFile.php b/includes/filerepo/file/OldLocalFile.php
index 419c395747..ebd83c4df0 100644
--- a/includes/filerepo/file/OldLocalFile.php
+++ b/includes/filerepo/file/OldLocalFile.php
@@ -3,13 +3,13 @@
  * Old file in the oldimage table
  *
  * @file
- * @ingroup FileRepo
+ * @ingroup FileAbstraction
  */
 
 /**
  * Class to represent a file in the oldimage table
  *
- * @ingroup FileRepo
+ * @ingroup FileAbstraction
  */
 class OldLocalFile extends LocalFile {
 	var $requestedTime, $archive_name;
diff --git a/includes/filerepo/file/UnregisteredLocalFile.php b/includes/filerepo/file/UnregisteredLocalFile.php
index 65a18a5062..cd9d3d028d 100644
--- a/includes/filerepo/file/UnregisteredLocalFile.php
+++ b/includes/filerepo/file/UnregisteredLocalFile.php
@@ -3,7 +3,7 @@
  * File without associated database record
  *
  * @file
- * @ingroup FileRepo
+ * @ingroup FileAbstraction
  */
 
 /**
@@ -16,7 +16,7 @@
  * lots of functions missing. It is used by the WebStore extension in the
  * standalone role.
  *
- * @ingroup FileRepo
+ * @ingroup FileAbstraction
  */
 class UnregisteredLocalFile extends File {
 	var $title, $path, $mime, $dims;
-- 
2.20.1