r110938 MediaWiki - Code Review archive

Repository:MediaWiki
Revision:< r110937‎ | r110938 | r110939 >
Date:15:51, 8 February 2012
Author:hashar
Status:ok (Comments)
Tags:
Comment:
enhance filerepo doc structure
Modified paths:
  • /trunk/phase3/includes/filerepo/FileRepo.php (modified) (history)
  • /trunk/phase3/includes/filerepo/RepoGroup.php (modified) (history)
  • /trunk/phase3/includes/filerepo/backend/FileBackend.php (modified) (history)
  • /trunk/phase3/includes/filerepo/backend/lockmanager/LSLockManager.php (modified) (history)
  • /trunk/phase3/includes/filerepo/backend/lockmanager/LockManager.php (modified) (history)
  • /trunk/phase3/includes/filerepo/file/ArchivedFile.php (modified) (history)
  • /trunk/phase3/includes/filerepo/file/File.php (modified) (history)
  • /trunk/phase3/includes/filerepo/file/ForeignAPIFile.php (modified) (history)
  • /trunk/phase3/includes/filerepo/file/ForeignDBFile.php (modified) (history)
  • /trunk/phase3/includes/filerepo/file/LocalFile.php (modified) (history)
  • /trunk/phase3/includes/filerepo/file/OldLocalFile.php (modified) (history)
  • /trunk/phase3/includes/filerepo/file/UnregisteredLocalFile.php (modified) (history)

Diff [purge]

Index: trunk/phase3/includes/filerepo/file/OldLocalFile.php
——@@ -3,13 +3,13 @@
44 * Old file in the oldimage table
55 *
66 * @file
7 - * @ingroup FileRepo
 7+ * @ingroup FileAbstraction
88 */
99
1010 /**
1111 * Class to represent a file in the oldimage table
1212 *
13 - * @ingroup FileRepo
 13+ * @ingroup FileAbstraction
1414 */
1515 class OldLocalFile extends LocalFile {
1616 var $requestedTime, $archive_name;
Index: trunk/phase3/includes/filerepo/file/LocalFile.php
——@@ -3,7 +3,7 @@
44 * Local file in the wiki's own database
55 *
66 * @file
7 - * @ingroup FileRepo
 7+ * @ingroup FileAbstraction
88 */
99
1010 /**
——@@ -26,7 +26,7 @@
2727 * The convenience functions wfLocalFile() and wfFindFile() should be sufficient
2828 * in most cases.
2929 *
30 - * @ingroup FileRepo
 30+ * @ingroup FileAbstraction
3131 */
3232 class LocalFile extends File {
3333 /**#@+
——@@ -1432,7 +1432,7 @@
14331433
14341434 /**
14351435 * Helper class for file deletion
1436 - * @ingroup FileRepo
 1436+ * @ingroup FileAbstraction
14371437 */
14381438 class LocalFileDeleteBatch {
14391439
——@@ -1749,7 +1749,7 @@
17501750
17511751 /**
17521752 * Helper class for file undeletion
1753 - * @ingroup FileRepo
 1753+ * @ingroup FileAbstraction
17541754 */
17551755 class LocalFileRestoreBatch {
17561756 /**
——@@ -2097,7 +2097,7 @@
20982098
20992099 /**
21002100 * Helper class for file movement
2101 - * @ingroup FileRepo
 2101+ * @ingroup FileAbstraction
21022102 */
21032103 class LocalFileMoveBatch {
21042104
Index: trunk/phase3/includes/filerepo/file/UnregisteredLocalFile.php
——@@ -3,7 +3,7 @@
44 * File without associated database record
55 *
66 * @file
7 - * @ingroup FileRepo
 7+ * @ingroup FileAbstraction
88 */
99
1010 /**
——@@ -16,7 +16,7 @@
1717 * lots of functions missing. It is used by the WebStore extension in the
1818 * standalone role.
1919 *
20 - * @ingroup FileRepo
 20+ * @ingroup FileAbstraction
2121 */
2222 class UnregisteredLocalFile extends File {
2323 var $title, $path, $mime, $dims;
Index: trunk/phase3/includes/filerepo/file/File.php
——@@ -1,9 +1,16 @@
22 <?php
33 /**
 4+ * @defgroup FileAbstraction File abstraction
 5+ * @ingroup FileRepo
 6+ *
 7+ * Represents files in a repository.
 8+ */
 9+
 10+/**
411 * Base code for files.
512 *
613 * @file
7 - * @ingroup FileRepo
 14+ * @ingroup FileAbstraction
815 */
916
1017 /**
——@@ -23,7 +30,7 @@
2431 * The convenience functions wfLocalFile() and wfFindFile() should be sufficient
2532 * in most cases.
2633 *
27 - * @ingroup FileRepo
 34+ * @ingroup FileAbstraction
2835 */
2936 abstract class File {
3037 const DELETED_FILE = 1;
Index: trunk/phase3/includes/filerepo/file/ForeignDBFile.php
——@@ -3,13 +3,13 @@
44 * Foreign file with an accessible MediaWiki database
55 *
66 * @file
7 - * @ingroup FileRepo
 7+ * @ingroup FileAbstraction
88 */
99
1010 /**
1111 * Foreign file with an accessible MediaWiki database
1212 *
13 - * @ingroup FileRepo
 13+ * @ingroup FileAbstraction
1414 */
1515 class ForeignDBFile extends LocalFile {
1616
Index: trunk/phase3/includes/filerepo/file/ForeignAPIFile.php
——@@ -3,14 +3,14 @@
44 * Foreign file accessible through api.php requests.
55 *
66 * @file
7 - * @ingroup FileRepo
 7+ * @ingroup FileAbstraction
88 */
99
1010 /**
1111 * Foreign file accessible through api.php requests.
1212 * Very hacky and inefficient, do not use :D
1313 *
14 - * @ingroup FileRepo
 14+ * @ingroup FileAbstraction
1515 */
1616 class ForeignAPIFile extends File {
1717 private $mExists;
Index: trunk/phase3/includes/filerepo/file/ArchivedFile.php
——@@ -3,13 +3,13 @@
44 * Deleted file in the 'filearchive' table
55 *
66 * @file
7 - * @ingroup FileRepo
 7+ * @ingroup FileAbstraction
88 */
99
1010 /**
1111 * Class representing a row of the 'filearchive' table
1212 *
13 - * @ingroup FileRepo
 13+ * @ingroup FileAbstraction
1414 */
1515 class ArchivedFile {
1616 /**#@+
Index: trunk/phase3/includes/filerepo/backend/lockmanager/LSLockManager.php
——@@ -1,6 +1,8 @@
22 <?php
33
44 /**
 5+ * Manage locks using a lock daemon server.
 6+ *
57 * Version of LockManager based on using lock daemon servers.
68 * This is meant for multi-wiki systems that may share files.
79 * All locks are non-blocking, which avoids deadlocks.
Index: trunk/phase3/includes/filerepo/backend/lockmanager/LockManager.php
——@@ -1,5 +1,10 @@
22 <?php
33 /**
 4+ * @defgroup LockManager Lock management
 5+ * @ingroup FileBackend
 6+ */
 7+
 8+/**
49 * @file
510 * @ingroup LockManager
611 * @author Aaron Schulz
——@@ -7,13 +12,14 @@
813
914 /**
1015 * Class for handling resource locking.
 16+ *
1117 * Locks on resource keys can either be shared or exclusive.
12 - *
 18+ *
1319 * Implementations must keep track of what is locked by this proccess
1420 * in-memory and support nested locking calls (using reference counting).
1521 * At least LOCK_UW and LOCK_EX must be implemented. LOCK_SH can be a no-op.
1622 * Locks should either be non-blocking or have low wait timeouts.
17 - *
 23+ *
1824 * Subclasses should avoid throwing exceptions at all costs.
1925 *
2026 * @ingroup LockManager
——@@ -94,6 +100,8 @@
95101 }
96102
97103 /**
 104+ * Self releasing locks
 105+ *
98106 * LockManager helper class to handle scoped locks, which
99107 * release when an object is destroyed or goes out of scope.
100108 *
Index: trunk/phase3/includes/filerepo/backend/FileBackend.php
——@@ -1,5 +1,12 @@
22 <?php
33 /**
 4+ * @defgroup FileBackend File backend
 5+ * @ingroup FileRepo
 6+ *
 7+ * This module regroup classes meant for MediaWiki to interacts with
 8+ */
 9+
 10+/**
411 * @file
512 * @ingroup FileBackend
613 * @author Aaron Schulz
——@@ -7,6 +14,7 @@
815
916 /**
1017 * Base class for all file backend classes (including multi-write backends).
 18+ *
1119 * This class defines the methods as abstract that subclasses must implement.
1220 * Outside callers can assume that all backends will have these functions.
1321 *
——@@ -698,7 +706,8 @@
699707 }
700708
701709 /**
702 - * Base class for all backends associated with a particular storage medium.
 710+ * @brief Base class for all backends associated with a particular storage medium.
 711+ *
703712 * This class defines the methods as abstract that subclasses must implement.
704713 * Outside callers should *not* use functions with "Internal" in the name.
705714 *
——@@ -1255,7 +1264,7 @@
12561265 }
12571266
12581267 /**
1259 - * @see FileBackend::getFileList()
 1268+ * @copydoc FileBackend::getFileList()
12601269 */
12611270 final public function getFileList( array $params ) {
12621271 list( $fullCont, $dir, $shard ) = $this->resolveStoragePath( $params['dir'] );
——@@ -1625,7 +1634,7 @@
16261635 * FileBackendStore helper function to handle file listings that span container shards.
16271636 * Do not use this class from places outside of FileBackendStore.
16281637 *
1629 - * @ingroup FileBackendStore
 1638+ * @ingroup FileBackend
16301639 */
16311640 class FileBackendStoreShardListIterator implements Iterator {
16321641 /* @var FileBackendStore */
Index: trunk/phase3/includes/filerepo/RepoGroup.php
——@@ -7,10 +7,6 @@
88 */
99
1010 /**
11 - * @defgroup FileRepo FileRepo
12 - */
13 -
14 -/**
1511 * Prioritized list of file repositories
1612 *
1713 * @ingroup FileRepo
Index: trunk/phase3/includes/filerepo/FileRepo.php
——@@ -1,5 +1,13 @@
22 <?php
33 /**
 4+ * @defgroup FileRepo File Repository
 5+ *
 6+ * @brief This module handles how MediaWiki interacts with filesystems.
 7+ *
 8+ * @details
 9+ */
 10+
 11+/**
412 * Base code for file repositories.
513 *
614 * @file

Follow-up revisions

RevisionCommit summaryAuthorDate
r111036reword doc from r110938hashar14:41, 9 February 2012

Comments

#Comment by Aaron Schulz (talk | contribs)   16:39, 8 February 2012

Does @copydoc work for our doxygen? If so, a lot more @see statements could be switched over.

#Comment by Hashar (talk | contribs)   16:40, 8 February 2012

It works for me. Not sure our good old version does :/ Something to look at later probably.

#Comment by Aaron Schulz (talk | contribs)   23:08, 8 February 2012 
This module regroup classes meant for MediaWiki to interacts with

Can this be reworded to make sense? :)

#Comment by Hashar (talk | contribs)   14:41, 9 February 2012

Reworded with r111036 and checked by Reedy.

Status & tagging log