Improve documentation of constants throughout the codebase

The most notable improvements I was able to fit into this patch can be
seen in the User class, as well as in AbstractRestriction.

Our documentation generator ignores the @const tag. It's not needed. Just
have a comment above a constant and it will show up in the generated
documentation.

Using @var is misleading because a constant is not a "variable". The type
of a constant is strictly derived from it's value. Documenting the type
typically does not provide useful information. Doxygen does not understand
the type, but ignores any @… tag and renders everything else as plain text.

I can split this patch if you prefer. Please tell me.

Change-Id: I8019ae45c049822cdc1768d895ea3e3216c6db5f

diff --git a/includes/MergeHistory.php b/includes/MergeHistory.php
index 0914a9b..6bd4471 100644 (file)
--- a/includes/MergeHistory.php
+++ b/includes/MergeHistory.php
@@ -32,7 +32,7 @@ use Wikimedia\Rdbms\IDatabase;
  */
 class MergeHistory {
 
-       /** @const int Maximum number of revisions that can be merged at once */
+       /** Maximum number of revisions that can be merged at once */
        const REVISION_LIMIT = 5000;
 
        /** @var Title Page from which history will be merged */

diff --git a/includes/block/Restriction/AbstractRestriction.php b/includes/block/Restriction/AbstractRestriction.php
index c89ed72..9fb7603 100644 (file)
--- a/includes/block/Restriction/AbstractRestriction.php
+++ b/includes/block/Restriction/AbstractRestriction.php
@@ -25,12 +25,14 @@ namespace MediaWiki\Block\Restriction;
 abstract class AbstractRestriction implements Restriction {
 
        /**
-        * @var string
+        * String constant identifying the type of restriction. Expected to be overriden in subclasses
+        * with a non-empty string value.
         */
        const TYPE = '';
 
        /**
-        * @var int
+        * Numeric type identifier. Expected to be overriden in subclasses with a non-zero integer
+        * number. Must not exceed 127 to fit into a TINYINT database field.
         */
        const TYPE_ID = 0;
 

diff --git a/includes/block/Restriction/Restriction.php b/includes/block/Restriction/Restriction.php
index fdf223a..d717fe7 100644 (file)
--- a/includes/block/Restriction/Restriction.php
+++ b/includes/block/Restriction/Restriction.php
@@ -61,7 +61,7 @@ interface Restriction {
         * Gets the id of the type of restriction. This id is used in the database.
         *
         * @since 1.33
-        * @return string
+        * @return int
         */
        public static function getTypeId();
 

diff --git a/includes/media/DjVuImage.php b/includes/media/DjVuImage.php
index adcac25..9aa1d53 100644 (file)
--- a/includes/media/DjVuImage.php
+++ b/includes/media/DjVuImage.php
@@ -34,8 +34,9 @@
  * @ingroup Media
  */
 class DjVuImage {
+
        /**
-        * @const DJVUTXT_MEMORY_LIMIT Memory limit for the DjVu description software
+        * Memory limit for the DjVu description software
         */
        const DJVUTXT_MEMORY_LIMIT = 300000;
 

diff --git a/includes/search/SearchEngine.php b/includes/search/SearchEngine.php
index 0b29dd7..405db44 100644 (file)
--- a/includes/search/SearchEngine.php
+++ b/includes/search/SearchEngine.php
@@ -56,16 +56,16 @@ abstract class SearchEngine {
        /** @var array Feature values */
        protected $features = [];
 
-       /** @const string profile type for completionSearch */
+       /** Profile type for completionSearch */
        const COMPLETION_PROFILE_TYPE = 'completionSearchProfile';
 
-       /** @const string profile type for query independent ranking features */
+       /** Profile type for query independent ranking features */
        const FT_QUERY_INDEP_PROFILE_TYPE = 'fulltextQueryIndepProfile';
 
-       /** @const int flag for legalSearchChars: includes all chars allowed in a search query */
+       /** Integer flag for legalSearchChars: includes all chars allowed in a search query */
        const CHARS_ALL = 1;
 
-       /** @const int flag for legalSearchChars: includes all chars allowed in a search term */
+       /** Integer flag for legalSearchChars: includes all chars allowed in a search term */
        const CHARS_NO_SYNTAX = 2;
 
        /**

diff --git a/includes/search/SearchResultSet.php b/includes/search/SearchResultSet.php
index 2f1a5c2..18331dd 100644 (file)
--- a/includes/search/SearchResultSet.php
+++ b/includes/search/SearchResultSet.php
@@ -25,17 +25,16 @@
  * @ingroup Search
  */
 class SearchResultSet implements Countable, IteratorAggregate {
+
        /**
-        * Types of interwiki results
-        */
-       /**
-        * Results that are displayed only together with existing main wiki results
-        * @var int
+        * Identifier for interwiki results that are displayed only together with existing main wiki
+        * results.
         */
        const SECONDARY_RESULTS = 0;
+
        /**
-        * Results that can displayed even if no existing main wiki results exist
-        * @var int
+        * Identifier for interwiki results that can be displayed even if no existing main wiki results
+        * exist.
         */
        const INLINE_RESULTS = 1;
 

diff --git a/includes/user/User.php b/includes/user/User.php
index 8173f5d..59cea66 100644 (file)
--- a/includes/user/User.php
+++ b/includes/user/User.php
@@ -45,18 +45,20 @@ use Wikimedia\Rdbms\IDatabase;
  * of the database.
  */
 class User implements IDBAccessObject, UserIdentity {
+
        /**
-        * @const int Number of characters in user_token field.
+        * Number of characters required for the user_token field.
         */
        const TOKEN_LENGTH = 32;
 
        /**
-        * @const string An invalid value for user_token
+        * An invalid string value for the user_token field.
         */
        const INVALID_TOKEN = '*** INVALID ***';
 
        /**
-        * @const int Serialized record version.
+        * Version number to tag cached versions of serialized User objects. Should be increased when
+        * {@link $mCacheVars} or one of it's members changes.
         */
        const VERSION = 13;
 

diff --git a/includes/watcheditem/NoWriteWatchedItemStore.php b/includes/watcheditem/NoWriteWatchedItemStore.php
index 2801207..eabdb07 100644 (file)
--- a/includes/watcheditem/NoWriteWatchedItemStore.php
+++ b/includes/watcheditem/NoWriteWatchedItemStore.php
@@ -32,9 +32,6 @@ class NoWriteWatchedItemStore implements WatchedItemStoreInterface {
         */
        private $actualStore;
 
-       /**
-        * @var string
-        */
        const DB_READONLY_ERROR = 'The watchlist is currently readonly.';
 
        /**