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

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 */

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;
 

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();
 

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;
 

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;
 
 	/**

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;
 

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;
 

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.';
 
 	/**