Improve class property documentation

Reformat existing documentation to match the format

Change-Id: I190b54b5e962f17bab6502dd1b3c02f11dc926d2

.phpcs.xml

@@ -11,11 +11,8 @@
 		<exclude name="MediaWiki.Commenting.PropertyDocumentation.MissingDocumentationProtected" />
 		<exclude name="MediaWiki.Commenting.PropertyDocumentation.MissingDocumentationPublic" />
 		<exclude name="MediaWiki.Commenting.PropertyDocumentation.MissingVar" />
-		<exclude name="MediaWiki.Commenting.PropertyDocumentation.NotShortBoolVar" />
-		<exclude name="MediaWiki.Commenting.PropertyDocumentation.NotShortIntVar" />
 		<exclude name="MediaWiki.Commenting.PropertyDocumentation.SpacingAfter" />
 		<exclude name="MediaWiki.Commenting.PropertyDocumentation.WrongStyle" />
-		<exclude name="MediaWiki.Commenting.RedundantVarName.Found" /><!-- autofix -->
 		<exclude name="MediaWiki.ControlStructures.AssignmentInControlStructures.AssignmentInControlStructures" />
 		<exclude name="MediaWiki.NamingConventions.LowerCamelFunctionsName.FunctionName" />
 		<exclude name="MediaWiki.Usage.DbrQueryUsage.DbrQueryFound" />

includes/Html.php

@@ -47,7 +47,7 @@ use MediaWiki\MediaWikiServices;
  * @since 1.16
  */
 class Html {
-	// List of void elements from HTML5, section 8.1.2 as of 2016-09-19
+	/** @var string[] List of void elements from HTML5, section 8.1.2 as of 2016-09-19 */
 	private static $voidElements = [
 		'area',
 		'base',
@@ -66,8 +66,11 @@ class Html {
 		'wbr',
 	];
 
-	// Boolean attributes, which may have the value omitted entirely.  Manually
-	// collected from the HTML5 spec as of 2011-08-12.
+	/**
+	 * Boolean attributes, which may have the value omitted entirely.  Manually
+	 * collected from the HTML5 spec as of 2011-08-12.
+	 * @var string[]
+	 */
 	private static $boolAttribs = [
 		'async',
 		'autofocus',

includes/OutputPage.php

@@ -224,7 +224,7 @@ class OutputPage extends ContextSource {
 	 */
 	private $mFeedLinks = [];
 
-	// Gwicke work on squid caching? Roughly from 2003.
+	/** @var bool Gwicke work on squid caching? Roughly from 2003. */
 	protected $mEnableClientCache = true;
 
 	/** @var bool Flag if output should only contain the body of the article. */

includes/PHPVersionCheck.php

@@ -52,7 +52,7 @@ class PHPVersionCheck {
 	var $format = 'text';
 
 	/**
-	 * @var string $scriptPath
+	 * @var string
 	 */
 	var $scriptPath = '/';
 

includes/Storage/DerivedPageDataUpdater.php

@@ -159,7 +159,7 @@ class DerivedPageDataUpdater implements IDBAccessObject, LoggerAwareInterface {
 	private $articleCountMethod;
 
 	/**
-	 * @var boolean see $wgRCWatchCategoryMembership
+	 * @var bool see $wgRCWatchCategoryMembership
 	 */
 	private $rcWatchCategoryMembership = false;
 

includes/Storage/PageUpdater.php

@@ -132,7 +132,7 @@ class PageUpdater {
 	private $hookContainer;
 
 	/**
-	 * @var boolean see $wgUseAutomaticEditSummaries
+	 * @var bool see $wgUseAutomaticEditSummaries
 	 * @see $wgUseAutomaticEditSummaries
 	 */
 	private $useAutomaticEditSummaries = true;
@@ -148,7 +148,7 @@ class PageUpdater {
 	private $usePageCreationLog = true;
 
 	/**
-	 * @var boolean see $wgAjaxEditStash
+	 * @var bool see $wgAjaxEditStash
 	 */
 	private $ajaxEditStash = true;
 

includes/Storage/SqlBlobStore.php

@@ -89,7 +89,7 @@ class SqlBlobStore implements IDBAccessObject, BlobStore {
 	private $legacyEncoding = false;
 
 	/**
-	 * @var boolean
+	 * @var bool
 	 */
 	private $useExternalStore = false;
 

includes/api/ApiQueryBacklinks.php

@@ -58,7 +58,7 @@ class ApiQueryBacklinks extends ApiQueryGeneratorBase {
 	private $redirTitles = [];
 	private $continueStr = null;
 
-	// output element name, database column field prefix, database table
+	/** @var string[][] output element name, database column field prefix, database table */
 	private $backlinksSettings = [
 		'backlinks' => [
 			'code' => 'bl',

includes/api/ApiQueryBacklinksprop.php

@@ -32,7 +32,7 @@
  */
 class ApiQueryBacklinksprop extends ApiQueryGeneratorBase {
 
-	// Data for the various modules implemented by this class
+	/** @var array Data for the various modules implemented by this class */
 	private static $settings = [
 		'redirects' => [
 			'code' => 'rd',

includes/block/BlockPermissionChecker.php

@@ -43,7 +43,7 @@ class BlockPermissionChecker {
 	private $target;
 
 	/**
-	 * @var int|null $targetType One of AbstractBlock::TYPE_* constants, or null when unknown
+	 * @var int|null One of AbstractBlock::TYPE_* constants, or null when unknown
 	 */
 	private $targetType = null;
 

includes/block/UnblockUser.php

@@ -36,16 +36,16 @@ use User;
  * @since 1.36
  */
 class UnblockUser {
-	/* @var BlockPermissionChecker */
+	/** @var BlockPermissionChecker */
 	private $blockPermissionChecker;
 
-	/* @var DatabaseBlockStore */
+	/** @var DatabaseBlockStore */
 	private $blockStore;
 
-	/* @var HookRunner */
+	/** @var HookRunner */
 	private $hookRunner;
 
-	/* @var User|string */
+	/** @var User|string */
 	private $target;
 
 	/** @var int */

includes/cache/FileCacheBase.php

@@ -34,7 +34,7 @@ abstract class FileCacheBase {
 	protected $mExt = 'cache';
 	protected $mFilePath;
 	protected $mUseGzip;
-	/* lazy loaded */
+	/** @var bool|null lazy loaded */
 	protected $mCached;
 
 	/* @todo configurable? */

includes/htmlform/HTMLForm.php

@@ -135,7 +135,7 @@ use MediaWiki\HookContainer\ProtectedHookAccessorTrait;
 class HTMLForm extends ContextSource {
 	use ProtectedHookAccessorTrait;
 
-	// A mapping of 'type' inputs onto standard HTMLFormField subclasses
+	/** @var string[] A mapping of 'type' inputs onto standard HTMLFormField subclasses */
 	public static $typeMappings = [
 		'api' => HTMLApiField::class,
 		'text' => HTMLTextField::class,
@@ -273,6 +273,7 @@ class HTMLForm extends ContextSource {
 	 *
 	 * Subclasses may set this to false to render subsections after fields
 	 * instead.
+	 * @var bool
 	 */
 	protected $mSubSectionBeforeFields = true;
 

includes/libs/ExplodeIterator.php

@@ -28,16 +28,22 @@
  * Except it doesn't use 193 byte per element
  */
 class ExplodeIterator implements Iterator {
-	// The subject string
-	private $subject, $subjectLength;
+	/** @var string The subject string */
+	private $subject;
 
-	// The delimiter
-	private $delim, $delimLength;
+	/** @var int The subject string length */
+	private $subjectLength;
 
-	// The position of the start of the line
+	/** @var string The delimiter */
+	private $delim;
+
+	/** @var int The delimiter string length */
+	private $delimLength;
+
+	/** @var int The position of the start of the line */
 	private $curPos;
 
-	// The position after the end of the next delimiter
+	/** @var int The position after the end of the next delimiter */
 	private $endPos;
 
 	/** @var string|false The current token */

includes/libs/rdbms/database/Database.php

@@ -172,7 +172,7 @@ abstract class Database implements IDatabase, IMaintainableDatabase, LoggerAware
 	/** @var bool Whether to suppress triggering of transaction end callbacks */
 	private $trxEndCallbacksSuppressed = false;
 
-	/** @var integer|null Rows affected by the last query to query() or its CRUD wrappers */
+	/** @var int|null Rows affected by the last query to query() or its CRUD wrappers */
 	protected $affectedRowCount;
 
 	/** @var float UNIX timestamp */

includes/page/CategoryPage.php

@@ -28,7 +28,7 @@
  * @method WikiCategoryPage getPage() Set by overwritten newPage() in this class
  */
 class CategoryPage extends Article {
-	# Subclasses can change this to override the viewer class.
+	/** @var string Subclasses can change this to override the viewer class. */
 	protected $mCategoryViewerClass = CategoryViewer::class;
 
 	/**

includes/resourceloader/ResourceLoaderOOUIModule.php

@@ -48,12 +48,12 @@ trait ResourceLoaderOOUIModule {
 		'icons-wikimedia',
 	];
 
-	// Note that keys must be lowercase, values TitleCase.
+	/** @var string[] Note that keys must be lowercase, values TitleCase. */
 	protected static $builtinSkinThemeMap = [
 		'default' => 'WikimediaUI',
 	];
 
-	// Note that keys must be TitleCase.
+	/** @var string[][] Note that keys must be TitleCase. */
 	protected static $builtinThemePaths = [
 		'WikimediaUI' => [
 			'scripts' => 'resources/lib/ooui/oojs-ui-wikimediaui.js',

includes/resourceloader/ResourceLoaderWikiModule.php

@@ -53,31 +53,34 @@ use Wikimedia\Timestamp\ConvertibleTimestamp;
  * @since 1.17
  */
 class ResourceLoaderWikiModule extends ResourceLoaderModule {
-	// Origin defaults to users with sitewide authority
+	/** @var string Origin defaults to users with sitewide authority */
 	protected $origin = self::ORIGIN_USER_SITEWIDE;
 
-	// In-process cache for title info, structured as an array
-	// [
-	//  <batchKey> // Pipe-separated list of sorted keys from getPages
-	//   => [
-	//     <titleKey> => [ // Normalised title key
-	//       'page_len' => ..,
-	//       'page_latest' => ..,
-	//       'page_touched' => ..,
-	//     ]
-	//   ]
-	// ]
-	// @see self::fetchTitleInfo()
-	// @see self::makeTitleKey()
+	/**
+	 * In-process cache for title info, structured as an array
+	 * [
+	 *  <batchKey> // Pipe-separated list of sorted keys from getPages
+	 *   => [
+	 *     <titleKey> => [ // Normalised title key
+	 *       'page_len' => ..,
+	 *       'page_latest' => ..,
+	 *       'page_touched' => ..,
+	 *     ]
+	 *   ]
+	 * ]
+	 * @see self::fetchTitleInfo()
+	 * @see self::makeTitleKey()
+	 * @var array
+	 */
 	protected $titleInfo = [];
 
-	// List of page names that contain CSS
+	/** @var array List of page names that contain CSS */
 	protected $styles = [];
 
-	// List of page names that contain JavaScript
+	/** @var array List of page names that contain JavaScript */
 	protected $scripts = [];
 
-	// Group of module
+	/** @var string|null Group of module */
 	protected $group;
 
 	/**
@@ -141,7 +144,7 @@ class ResourceLoaderWikiModule extends ResourceLoaderModule {
 	/**
 	 * Get group name
 	 *
-	 * @return string
+	 * @return string|null
 	 */
 	public function getGroup() {
 		return $this->group;

includes/search/SearchResultSet.php

@@ -44,7 +44,7 @@ class SearchResultSet extends BaseSearchResultSet {
 	protected $results;
 
 	/**
-	 * @var boolean True when there are more pages of search results available.
+	 * @var bool True when there are more pages of search results available.
 	 */
 	private $hasMoreResults;
 

includes/search/searchwidgets/SearchFormWidget.php

@@ -18,7 +18,7 @@ class SearchFormWidget {
 	protected $searchConfig;
 	/** @var array */
 	protected $profiles;
-	/** @var HookContainer $hookContainer */
+	/** @var HookContainer */
 	private $hookContainer;
 	/** @var HookRunner */
 	private $hookRunner;

includes/specialpage/ChangesListSpecialPage.php

@@ -90,14 +90,16 @@ abstract class ChangesListSpecialPage extends SpecialPage {
 	 */
 	private $filterGroupDefinitions;
 
-	// Same format as filterGroupDefinitions, but for a single group (reviewStatus)
-	// that is registered conditionally.
+	/**
+	 * @var array Same format as filterGroupDefinitions, but for a single group (reviewStatus)
+	 * that is registered conditionally.
+	 */
 	private $legacyReviewStatusFilterGroupDefinition;
 
-	// Single filter group registered conditionally
+	/** @var array Single filter group registered conditionally */
 	private $reviewStatusFilterGroupDefinition;
 
-	// Single filter group registered conditionally
+	/** @var array Single filter group registered conditionally */
 	private $hideCategorizationFilterDefinition;
 
 	/**

includes/specialpage/RedirectSpecialPage.php

@@ -29,10 +29,10 @@
  * @ingroup SpecialPage
  */
 abstract class RedirectSpecialPage extends UnlistedSpecialPage {
-	// Query parameters that can be passed through redirects
+	/** @var array Query parameters that can be passed through redirects */
 	protected $mAllowedRedirectParams = [];
 
-	// Query parameters added by redirects
+	/** @var array Query parameters added by redirects */
 	protected $mAddedRedirectParams = [];
 
 	/**

includes/specialpage/SpecialPage.php

@@ -39,24 +39,28 @@ use MediaWiki\Navigation\PrevNextNavigationRenderer;
  * @ingroup SpecialPage
  */
 class SpecialPage implements MessageLocalizer {
-	// The canonical name of this special page
-	// Also used for the default <h1> heading, @see getDescription()
+	/**
+	 * @var string The canonical name of this special page
+	 * Also used for the default <h1> heading, @see getDescription()
+	 */
 	protected $mName;
 
-	// The local name of this special page
+	/** @var string The local name of this special page */
 	private $mLocalName;
 
-	// Minimum user level required to access this page, or "" for anyone.
-	// Also used to categorise the pages in Special:Specialpages
+	/**
+	 * @var string Minimum user level required to access this page, or "" for anyone.
+	 * Also used to categorise the pages in Special:Specialpages
+	 */
 	protected $mRestriction;
 
-	// Listed in Special:Specialpages?
+	/** @var bool Listed in Special:Specialpages? */
 	private $mListed;
 
-	// Whether or not this special page is being included from an article
+	/** @var bool Whether or not this special page is being included from an article */
 	protected $mIncluding;
 
-	// Whether the special page can be included in an article
+	/** @var bool Whether the special page can be included in an article */
 	protected $mIncludable;
 
 	/**

includes/specials/SpecialUploadStash.php

@@ -34,7 +34,7 @@
  * @ingroup Upload
  */
 class SpecialUploadStash extends UnlistedSpecialPage {
-	// UploadStash
+	/** @var UploadStash|null */
 	private $stash;
 
 	/** @var LocalRepo */

includes/specials/SpecialUserrights.php

@@ -38,7 +38,7 @@ class UserrightsPage extends SpecialPage {
 	 */
 	protected $mTarget;
 	/**
-	 * @var null|User $mFetchedUser The user object of the target username or null.
+	 * @var null|User The user object of the target username or null.
 	 */
 	protected $mFetchedUser = null;
 	protected $isself = false;

includes/specials/forms/PreferencesFormOOUI.php

@@ -24,7 +24,7 @@
  * @since 1.32
  */
 class PreferencesFormOOUI extends OOUIHTMLForm {
-	// Override default value from HTMLForm
+	/** @var bool Override default value from HTMLForm */
 	protected $mSubSectionBeforeFields = false;
 
 	/** @var User|null */

includes/upload/UploadBase.php

@@ -173,7 +173,7 @@ abstract class UploadBase {
 		return $user->pingLimiter( 'upload' );
 	}
 
-	// Upload handlers. Should probably just be a global.
+	/** @var string[] Upload handlers. Should probably just be a global. */
 	private static $uploadHandlers = [ 'Stash', 'File', 'Url' ];
 
 	/**

includes/upload/UploadFromStash.php

@@ -35,10 +35,10 @@ class UploadFromStash extends UploadBase {
 	protected $mFileProps;
 	protected $mSourceType;
 
-	// an instance of UploadStash
+	/** @var UploadStash */
 	private $stash;
 
-	// LocalFile repo
+	/** @var FileRepo */
 	private $repo;
 
 	/**

includes/upload/UploadStash.php

@@ -63,13 +63,13 @@ class UploadStash {
 	 */
 	public $repo;
 
-	// array of initialized repo objects
+	/** @var array array of initialized repo objects */
 	protected $files = [];
 
-	// cache of the file metadata that's stored in the database
+	/** @var array cache of the file metadata that's stored in the database */
 	protected $fileMetadata = [];
 
-	// fileprops cache
+	/** @var array fileprops cache */
 	protected $fileProps = [];
 
 	// current user

includes/utils/BatchRowIterator.php

@@ -89,7 +89,7 @@ class BatchRowIterator implements RecursiveIterator {
 	protected $options = [];
 
 	/**
-	 * For debugging which method is using this class.
+	 * @var string|null For debugging which method is using this class.
 	 */
 	protected $caller;
 

includes/utils/BatchRowWriter.php

@@ -41,7 +41,7 @@ class BatchRowWriter {
 	protected $clusterName;
 
 	/**
-	 * For debugging which method is using this class.
+	 * @var string|null For debugging which method is using this class.
 	 */
 	protected $caller;
 

languages/LanguageConverter.php

@@ -69,7 +69,7 @@ abstract class LanguageConverter implements ILanguageConverter {
 	 */
 	protected $mTables;
 
-	// 'bidirectional' 'unidirectional' 'disable' for each variant
+	/** @var string[] One of 'bidirectional' 'unidirectional' 'disable' for each variant */
 	public $mManualLevel;
 
 	/**

languages/data/CrhExceptions.php

@@ -116,8 +116,10 @@ class CrhExceptions {
 			$this->Latn2CyrlPatterns, $this->CyrlCleanUpRegexes ];
 	}
 
-	# map Latin to Cyrillic and back, simple string match only (no regex)
-	# variants: all lowercase, all uppercase, first letter capitalized
+	/**
+	 * @var string[] map Latin to Cyrillic and back, simple string match only (no regex)
+	 * variants: all lowercase, all uppercase, first letter capitalized
+	 */
 	private $ManyToOneC2LMappings = [
 		# Carefully ordered many-to-one mappings
 		# these are ordered so C2L is correct (the later Latin one)
@@ -128,8 +130,10 @@ class CrhExceptions {
 		'mesul' => 'месуль', 'mesül' => 'месуль',
 	];
 
-	# map Cyrillic to Latin and back, simple string match only (no regex)
-	# variants: all lowercase, all uppercase, first letter capitalized
+	/**
+	 * @var string[] map Cyrillic to Latin and back, simple string match only (no regex)
+	 * variants: all lowercase, all uppercase, first letter capitalized
+	 */
 	private $multiCaseMappings = [
 
 		#### Cyrillic to Latin
@@ -344,8 +348,10 @@ class CrhExceptions {
 
 	];
 
-	# map Cyrillic to Latin and back, simple string match only (no regex)
-	# no variants: map exactly as is
+	/**
+	 * @var string[] map Cyrillic to Latin and back, simple string match only (no regex)
+	 * no variants: map exactly as is
+	 */
 	private $exactCaseMappings = [
 		# аббревиатуры
 		# abbreviations
@@ -354,11 +360,13 @@ class CrhExceptions {
 		'КъМПУ' => 'QMPU',
 	];
 
-	# map Cyrillic to Latin and back, match end of word
-	# variants: all lowercase, all uppercase, first letter capitalized
-	# "first letter capitalized" variant was in the source
-	# items with capture group refs (e.g., $1) are only mapped from the
-	# regex to the reference
+	/**
+	 * @var string[] map Cyrillic to Latin and back, match end of word
+	 * variants: all lowercase, all uppercase, first letter capitalized
+	 * "first letter capitalized" variant was in the source
+	 * items with capture group refs (e.g., $1) are only mapped from the
+	 * regex to the reference
+	 */
 	private $suffixMapping = [
 		# originally C2L
 		'иаль' => 'ial', 'нуль' => 'nul', 'кой' => 'köy', 'койнинъ' => 'köyniñ', 'койни' => 'köyni',
@@ -372,10 +380,12 @@ class CrhExceptions {
 
 	];
 
-	# map Cyrillic to Latin and back, match beginning of word
-	# variants: all lowercase, all uppercase, first letter capitalized
-	# items with capture group refs (e.g., $1) are only mapped from the
-	# regex to the reference
+	/**
+	 * @var string[] map Cyrillic to Latin and back, match beginning of word
+	 * variants: all lowercase, all uppercase, first letter capitalized
+	 * items with capture group refs (e.g., $1) are only mapped from the
+	 * regex to the reference
+	 */
 	private $prefixMapping = [
 		# originally C2L
 		'буюк([^ъ])' => 'büyük$1', 'бую([гдйлмнпрстчшc])(и)' => 'büyü$1$2',

maintenance/includes/Maintenance.php

@@ -71,32 +71,32 @@ abstract class Maintenance {
 	 */
 	protected $mParams = [];
 
-	// Array of mapping short parameters to long ones
+	/** @var array Mapping short parameters to long ones */
 	protected $mShortParamsMap = [];
 
-	// Array of desired/allowed args
+	/** @var array Desired/allowed args */
 	protected $mArgList = [];
 
-	// This is the list of options that were actually passed
+	/** @var array This is the list of options that were actually passed */
 	protected $mOptions = [];
 
-	// This is the list of arguments that were actually passed
+	/** @var array This is the list of arguments that were actually passed */
 	protected $mArgs = [];
 
-	// Allow arbitrary options to be passed, or only specified ones?
+	/** @var bool Allow arbitrary options to be passed, or only specified ones? */
 	protected $mAllowUnregisteredOptions = false;
 
-	// Name of the script currently running
+	/** @var string|null Name of the script currently running */
 	protected $mSelf;
 
-	// Special vars for params that are always used
+	/** @var bool Special vars for params that are always used */
 	protected $mQuiet = false;
 	protected $mDbUser, $mDbPass;
 
-	// A description of the script, children should change this via addDescription()
+	/** @var string A description of the script, children should change this via addDescription() */
 	protected $mDescription = '';
 
-	// Have we already loaded our user input?
+	/** @var bool Have we already loaded our user input? */
 	protected $mInputLoaded = false;
 
 	/**

maintenance/includes/TextPassDumper.php

@@ -49,9 +49,11 @@ class TextPassDumper extends BackupDumper {
 	/** @var string|bool */
 	private $thisRole = null;
 
-	// when we spend more than maxTimeAllowed seconds on this run, we continue
-	// processing until we write out the next complete page, then save output file(s),
-	// rename it/them and open new one(s)
+	/**
+	 * @var int when we spend more than maxTimeAllowed seconds on this run, we continue
+	 * processing until we write out the next complete page, then save output file(s),
+	 * rename it/them and open new one(s)
+	 */
 	public $maxTimeAllowed = 0; // 0 = no limit
 
 	protected $input = "php://stdin";

maintenance/language/digit2html.php

@@ -30,8 +30,10 @@ require_once __DIR__ . '/../Maintenance.php';
  */
 class Digit2Html extends Maintenance {
 
-	# A list of unicode numerals is available at:
-	# https://www.fileformat.info/info/unicode/category/Nd/list.htm
+	/**
+	 * @var string[] A list of unicode numerals is available at:
+	 * https://www.fileformat.info/info/unicode/category/Nd/list.htm
+	 */
 	private $mLangs = [
 		'Ar', 'As', 'Bh', 'Bo', 'Dz',
 		'Fa', 'Gu', 'Hi', 'Km', 'Kn',

tests/parser/ParserTestRunner.php

@@ -54,12 +54,12 @@ class ParserTestRunner {
 	];
 
 	/**
-	 * @var bool $useTemporaryTables Use temporary tables for the temporary database
+	 * @var bool Use temporary tables for the temporary database
 	 */
 	private $useTemporaryTables = true;
 
 	/**
-	 * @var array $setupDone The status of each setup function
+	 * @var array The status of each setup function
 	 */
 	private $setupDone = [
 		'staticSetup' => false,

tests/phpunit/includes/jobqueue/jobs/UserEditCountInitJobTest.php

@@ -7,7 +7,7 @@ use MediaWiki\MediaWikiServices;
  */
 class UserEditCountInitJobTest extends MediaWikiIntegrationTestCase {
 
-	/** @var User $user */
+	/** @var User */
 	private $user;
 
 	protected function setUp(): void {