From 18741b93060ec6d60da860da2e48894dd42002cd Mon Sep 17 00:00:00 2001 From: Thiemo Kreuz Date: Tue, 26 Feb 2019 14:02:50 +0100 Subject: [PATCH] Improve documentation of constants throughout the codebase MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit 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 --- includes/MergeHistory.php | 2 +- includes/block/Restriction/AbstractRestriction.php | 6 ++++-- includes/block/Restriction/Restriction.php | 2 +- includes/media/DjVuImage.php | 3 ++- includes/search/SearchEngine.php | 8 ++++---- includes/search/SearchResultSet.php | 13 ++++++------- includes/user/User.php | 8 +++++--- includes/watcheditem/NoWriteWatchedItemStore.php | 3 --- 8 files changed, 23 insertions(+), 22 deletions(-) diff --git a/includes/MergeHistory.php b/includes/MergeHistory.php index 0914a9b7d8..6bd4471723 100644 --- 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 c89ed72b1e..9fb7603582 100644 --- 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 fdf223a5ad..d717fe7e86 100644 --- 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 adcac2523a..9aa1d5313a 100644 --- 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 0b29dd7480..405db449e5 100644 --- 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 2f1a5c2457..18331ddc75 100644 --- 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 8173f5db8c..59cea665f5 100644 --- 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 28012078d0..eabdb077ad 100644 --- 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.'; /** -- 2.20.1