Add doc for every class member

Adding PHPdocs to every class members, in every file. This patch only
touches comments, and moved properties on their own lines. Note that
some of these properties would need to be moved, somehow changed, or
just removed (either because they're old, unused leftovers, or just
because we can move them to local scope), but I wanted to keep this
patch doc-only.

Change-Id: I9fe701445bea8f09d82783789ff1ec537ac6704b

includes/AFComputedVariable.php

@@ -5,8 +5,21 @@ use MediaWiki\MediaWikiServices;
 use MediaWiki\Logger\LoggerFactory;
 
 class AFComputedVariable {
-	public $mMethod, $mParameters;
+	/**
+	 * @var string The method used to compute the variable
+	 */
+	public $mMethod;
+	/**
+	 * @var array Parameters to be used with the specified method
+	 */
+	public $mParameters;
+	/**
+	 * @var array Cache containing User objects already constructed
+	 */
 	public static $userCache = [];
+	/**
+	 * @var array Cache containing Page objects already constructed
+	 */
 	public static $articleCache = [];
 
 	/**
@@ -140,7 +153,7 @@ class AFComputedVariable {
 
 	/**
 	 * @param AbuseFilterVariableHolder $vars
-	 * @return AFPData|array|int|mixed|null|string
+	 * @return AFPData
 	 * @throws MWException
 	 * @throws AFPException
 	 */

includes/AbuseFilter.php

@@ -13,7 +13,13 @@ use Wikimedia\Rdbms\IDatabase;
  * logging actions, etc.
  */
 class AbuseFilter {
+	/**
+	 * @var int How long to keep profiling data in cache (in seconds)
+	 */
 	public static $statsStoragePeriod = 86400;
+	/**
+	 * @var bool Whether the condition limit is enabled
+	 */
 	public static $condLimitEnabled = true;
 
 	/**
@@ -25,10 +31,15 @@ class AbuseFilter {
 	/** @var string The prefix to use for global filters */
 	const GLOBAL_FILTER_PREFIX = 'global-';
 
+	/**
+	 * @var int The amount of conditions currently used
+	 */
 	public static $condCount = 0;
 
-	/** @var array Map of (action ID => string[]) */
-	// FIXME: avoid global state here
+	/*
+	 * @var array Map of (action ID => string[])
+	 * @fixme avoid global state here
+	 */
 	public static $tagsToSet = [];
 
 	public static $history_mappings = [

includes/Views/AbuseFilterView.php

@@ -3,7 +3,26 @@
 use Wikimedia\Rdbms\IDatabase;
 
 abstract class AbuseFilterView extends ContextSource {
-	public $mFilter, $mHistoryID, $mSubmit, $mPage, $mParams;
+	/**
+	 * @var string The ID of the current filter
+	 */
+	public $mFilter;
+	/**
+	 * @var string The history ID of the current filter
+	 */
+	public $mHistoryID;
+	/**
+	 * @var bool Whether the form was submitted
+	 */
+	public $mSubmit;
+	/**
+	 * @var SpecialAbuseFilter The related special page object
+	 */
+	public $mPage;
+	/**
+	 * @var array The parameters of the current request
+	 */
+	public $mParams;
 
 	/**
 	 * @var \MediaWiki\Linker\LinkRenderer

includes/Views/AbuseFilterViewDiff.php

@@ -1,9 +1,21 @@
 <?php
 
 class AbuseFilterViewDiff extends AbuseFilterView {
+	/**
+	 * @var array|null The old version of the filter
+	 */
 	public $mOldVersion = null;
+	/**
+	 * @var array|null The new version of the filter
+	 */
 	public $mNewVersion = null;
+	/**
+	 * @var int|null The history ID of the next version, if any
+	 */
 	public $mNextHistoryId = null;
+	/**
+	 * @var int|null The ID of the filter
+	 */
 	public $mFilter = null;
 
 	/**

includes/Views/AbuseFilterViewEdit.php

@@ -1,7 +1,14 @@
 <?php
 
 class AbuseFilterViewEdit extends AbuseFilterView {
-	public static $mLoadedRow = null, $mLoadedActions = null;
+	/**
+	 * @var stdClass|null An abuse_filter row describing a filter
+	 */
+	public static $mLoadedRow = null;
+	/**
+	 * @var array|null An array of actions for the current filter
+	 */
+	public static $mLoadedActions = null;
 	/**
 	 * @param SpecialAbuseFilter $page
 	 * @param array $params

includes/Views/AbuseFilterViewExamine.php

@@ -1,7 +1,25 @@
 <?php
 
 class AbuseFilterViewExamine extends AbuseFilterView {
-	public $mCounter, $mSearchUser, $mSearchPeriodStart, $mSearchPeriodEnd;
+	/**
+	 * @var int Line number of the row, see RecentChange::$counter
+	 */
+	public $mCounter;
+	/**
+	 * @var string The user whose entries we're examinating
+	 */
+	public $mSearchUser;
+	/**
+	 * @var string The start time of the search period
+	 */
+	public $mSearchPeriodStart;
+	/**
+	 * @var string The end time of the search period
+	 */
+	public $mSearchPeriodEnd;
+	/**
+	 * @var string The ID of the filter we're examinating
+	 */
 	public $mTestFilter;
 
 	/**

includes/Views/AbuseFilterViewRevert.php

@@ -1,7 +1,25 @@
 <?php
 
 class AbuseFilterViewRevert extends AbuseFilterView {
-	public $origPeriodStart, $origPeriodEnd, $mPeriodStart, $mPeriodEnd;
+	/**
+	 * @var string The start time of the lookup period
+	 */
+	public $origPeriodStart;
+	/**
+	 * @var string The end time of the lookup period
+	 */
+	public $origPeriodEnd;
+	/**
+	 * @var string The same as $origPeriodStart
+	 */
+	public $mPeriodStart;
+	/**
+	 * @var string The same as $origPeriodEnd
+	 */
+	public $mPeriodEnd;
+	/**
+	 * @var string|null The reason provided for the revert
+	 */
 	public $mReason;
 
 	/**

includes/Views/AbuseFilterViewTestBatch.php

@@ -1,11 +1,39 @@
 <?php
 
 class AbuseFilterViewTestBatch extends AbuseFilterView {
-	// Hard-coded for now.
+	/**
+	 * @var int The limit of changes to test, hard coded for now
+	 */
 	protected static $mChangeLimit = 100;
 
-	public $mShowNegative, $mTestPeriodStart, $mTestPeriodEnd, $mTestPage;
-	public $mTestUser, $mExcludeBots, $mTestAction;
+	/**
+	 * @var bool Whether to show changes that don't trigger the specified pattern
+	 */
+	public $mShowNegative;
+	/**
+	 * @var string The start time of the lookup period
+	 */
+	public $mTestPeriodStart;
+	/**
+	 * @var string The end time of the lookup period
+	 */
+	public $mTestPeriodEnd;
+	/**
+	 * @var string The page of which edits we're interested in
+	 */
+	public $mTestPage;
+	/**
+	 * @var string The user whose actions we want to test
+	 */
+	public $mTestUser;
+	/**
+	 * @var bool Whether to exclude bot edits
+	 */
+	public $mExcludeBots;
+	/**
+	 * @var string The action (performed by the user) we want to search for
+	 */
+	public $mTestAction;
 
 	/**
 	 * Shows the page

includes/pagers/AbuseFilterExaminePager.php

@@ -1,7 +1,14 @@
 <?php
 
 class AbuseFilterExaminePager extends ReverseChronologicalPager {
-	public $mChangesList, $mPage;
+	/**
+	 * @var AbuseFilterChangesList Our changes list
+	 */
+	public $mChangesList;
+	/**
+	 * @var AbuseFilterViewExamine The associated view
+	 */
+	public $mPage;
 
 	/**
 	 * @param AbuseFilterViewExamine $page

includes/pagers/AbuseFilterHistoryPager.php

@@ -3,8 +3,22 @@
 use MediaWiki\Linker\LinkRenderer;
 
 class AbuseFilterHistoryPager extends TablePager {
-	public $mFilter, $mPage, $mUser;
+	/**
+	 * @var string The filter ID
+	 */
+	public $mFilter;
+	/**
+	 * @var AbuseFilterViewHistory The associated page
+	 */
+	public $mPage;
+	/**
+	 * @var string The user whose changes we're looking up for
+	 */
+	public $mUser;
 
+	/**
+	 * @var LinkRenderer
+	 */
 	protected $linkRenderer;
 	/**
 	 * @param string $filter

includes/pagers/AbuseFilterPager.php

@@ -12,7 +12,19 @@ class AbuseFilterPager extends TablePager {
 	 */
 	protected $linkRenderer;
 
-	public $mPage, $mConds, $mQuery;
+	/**
+	 * @var AbuseFilterViewList The associated page
+	 */
+	public $mPage;
+	/**
+	 * @var array Query WHERE conditions
+	 */
+	public $mConds;
+	/**
+	 * @var string[] Info used for searching patterns. The first element is the specified pattern,
+	 *   the second is the search mode (LIKE, RLIKE or IRLIKE)
+	 */
+	public $mQuery;
 
 	/**
 	 * @param AbuseFilterViewList $page

includes/parser/AFPData.php

@@ -23,7 +23,13 @@ class AFPData {
 		'\]' => ']',
 	];
 
+	/**
+	 * @var string One of the D* const from this class
+	 */
 	public $type;
+	/**
+	 * @var mixed|null|AFPData[] The actual data contained in this object
+	 */
 	public $data;
 
 	/**

includes/parser/AFPToken.php

@@ -48,8 +48,17 @@ class AFPToken {
 	const TCOMMA = 'T_COMMA';
 	const TSTATEMENTSEPARATOR = 'T_STATEMENT_SEPARATOR';
 
+	/**
+	 * @var string One of the T* constant from this class
+	 */
 	public $type;
+	/**
+	 * @var mixed|null The actual value of the token
+	 */
 	public $value;
+	/**
+	 * @var int The code offset where this token is found
+	 */
 	public $pos;
 
 	/**

includes/parser/AbuseFilterParser.php

@@ -5,16 +5,31 @@ use MediaWiki\Logger\LoggerFactory;
 use MediaWiki\MediaWikiServices;
 
 class AbuseFilterParser {
-	public $mTokens, $mPos, $mShortCircuit, $mAllowShort;
-	/** @var AFPToken The current token */
+	/**
+	 * @var array Contains the AFPTokens for the code being parsed
+	 */
+	public $mTokens;
+	/**
+	 * @var int The position of the current token
+	 */
+	public $mPos;
+	/**
+	 * @var bool Are we inside a short circuit evaluation?
+	 */
+	public $mShortCircuit;
+	/**
+	 * @var bool Are we allowed to use short-circuit evaluation?
+	 */
+	public $mAllowShort;
+	/**
+	 * @var AFPToken The current token
+	 */
 	public $mCur;
-
 	/**
 	 * @var AbuseFilterVariableHolder
 	 */
 	public $mVars;
 
-	// length,lcase,ucase,ccnorm,rmdoubles,specialratio,rmspecials,norm,count,get_matches
 	public static $mFunctions = [
 		'lcase' => 'funcLc',
 		'ucase' => 'funcUc',

includes/special/SpecialAbuseFilter.php

@@ -1,7 +1,14 @@
 <?php
 
 class SpecialAbuseFilter extends SpecialPage {
-	public $mFilter, $mHistoryID;
+	/**
+	 * @var int|string|null The current filter
+	 */
+	public $mFilter;
+	/**
+	 * @var string|null The history ID of the current version
+	 */
+	public $mHistoryID;
 
 	public function __construct() {
 		parent::__construct( 'AbuseFilter', 'abusefilter-view' );

includes/special/SpecialAbuseLog.php

@@ -2,35 +2,53 @@
 
 class SpecialAbuseLog extends SpecialPage {
 	/**
-	 * @var User
+	 * @var User The user whose AbuseLog entries are being searched
 	 */
 	protected $mSearchUser;
 
+	/**
+	 * @var string The start time of the search period
+	 */
 	protected $mSearchPeriodStart;
 
+	/**
+	 * @var string The end time of the search period
+	 */
 	protected $mSearchPeriodEnd;
 
 	/**
-	 * @var Title
+	 * @var Title The page of which AbuseLog entries are being searched
 	 */
 	protected $mSearchTitle;
 
 	/**
-	 * @var string
+	 * @var string The action performed by the user
 	 */
 	protected $mSearchAction;
 
 	/**
-	 * @var string
+	 * @var string The action taken by AbuseFilter
 	 */
 	protected $mSearchActionTaken;
 
+	/**
+	 * @var string The wiki name where we're performing the search
+	 */
 	protected $mSearchWiki;
 
+	/**
+	 * @var string|null The filter IDs we're looking for. Either a single one, or a pipe-separated list
+	 */
 	protected $mSearchFilter;
 
+	/**
+	 * @var string The visibility of entries we're interested in
+	 */
 	protected $mSearchEntries;
 
+	/**
+	 * @var string The impact of the user action, i.e. if the change has been saved
+	 */
 	protected $mSearchImpact;
 
 	/**

tests/phpunit/AFPDataTest.php

@@ -38,6 +38,7 @@ class AFPDataTest extends MediaWikiTestCase {
 	 * @return AbuseFilterParser
 	 */
 	public static function getParser() {
+		/** @var AbuseFilterParser|null The parser used for tests */
 		static $parser = null;
 		if ( !$parser ) {
 			$parser = new AbuseFilterParser();

tests/phpunit/AbuseFilterSaveTest.php

@@ -33,11 +33,12 @@
  * @covers AbuseFilterParser
  */
 class AbuseFilterSaveTest extends MediaWikiTestCase {
-	protected static $mUser, $mParameters;
+	/** @var User The user saving filters */
+	protected static $mUser;
+	/** @var array Parameters for the test set being executed */
+	protected static $mParameters;
 
-	/**
-	 * @var array This tables will be deleted in parent::tearDown
-	 */
+	/** @var array This tables will be deleted in parent::tearDown */
 	protected $tablesUsed = [
 		'abuse_filter',
 		'abuse_filter_action',