Fix code comments

Fixed some comments adding explanations, fixing syntax, and parameter types
for docblocks. Also fixed some whitespace mess, and added a missing use
statement.

Change-Id: I3547c90bdaa2cab5443e8bf0c63b217fe6ba663f

includes/AFComputedVariable.php

@@ -92,7 +92,7 @@ class AFComputedVariable {
 
 	/**
 	 * @param int $namespace
-	 * @param Title $title
+	 * @param string $title
 	 * @return Article
 	 */
 	public static function articleFromTitle( $namespace, $title ) {
@@ -119,7 +119,7 @@ class AFComputedVariable {
 	 * @return array
 	 */
 	public static function getLinksFromDB( $article ) {
-		// Stolen from ConfirmEdit
+		// Stolen from ConfirmEdit, SimpleCaptcha::getLinksFromTracker
 		$id = $article->getId();
 		if ( !$id ) {
 			return [];

includes/AbuseFilter.php

@@ -918,7 +918,7 @@ class AbuseFilter {
 
 			$global_filter = self::decodeGlobalName( $filter ) !== false;
 
-			// If the filter is throttled and throttling is available via object
+			// If the filter has "throttle" enabled and throttling is available via object
 			// caching, check to see if the user has hit the throttle.
 			if ( !empty( $actions['throttle'] ) && $wgMainCacheType !== CACHE_NONE ) {
 				$parameters = $actions['throttle']['parameters'];
@@ -2749,7 +2749,7 @@ class AbuseFilter {
 	}
 
 	/**
-	 * @param Title $title
+	 * @param Title|null $title
 	 * @param Page|null $page
 	 * @return AbuseFilterVariableHolder
 	 */
@@ -3004,7 +3004,7 @@ class AbuseFilter {
 	 * Note also that if the revision for any reason is not an Revision
 	 * the function returns with an empty string.
 	 *
-	 * @param Revision $revision a valid revision
+	 * @param Revision|null $revision a valid revision
 	 * @param int $audience one of:
 	 *      Revision::FOR_PUBLIC       to be displayed to all users
 	 *      Revision::FOR_THIS_USER    to be displayed to the given user

includes/AbuseFilterHooks.php

@@ -9,7 +9,7 @@ class AbuseFilterHooks {
 
 	/** @var AbuseFilterVariableHolder|bool */
 	public static $successful_action_vars = false;
-	/** @var WikiPage|Article|bool Make sure edit filter & edit save hooks match */
+	/** @var WikiPage|Article|bool|null Make sure edit filter & edit save hooks match */
 	public static $last_edit_page = false;
 	// So far, all of the error message out-params for these hooks accept HTML.
 

includes/Views/AbuseFilterViewEdit.php

@@ -130,7 +130,7 @@ class AbuseFilterViewEdit extends AbuseFilterView {
 	 * Builds the full form for edit filters.
 	 * Loads data either from the database or from the HTTP request.
 	 * The request takes precedence over the database
-	 * @param string $error An error message to show above the filter box.
+	 * @param string|null $error An error message to show above the filter box.
 	 * @param int $filter The filter ID
 	 * @param int|null $history_id The history ID of the filter, if applicable. Otherwise null
 	 * @return bool|string False if there is a failure building the editor,
@@ -493,7 +493,7 @@ class AbuseFilterViewEdit extends AbuseFilterView {
 	 * @param bool $set Whether or not the action is activated
 	 * @param array $parameters Action parameters
 	 * @param stdClass $row abuse_filter row object
-	 * @return string
+	 * @return string|\OOUI\FieldLayout
 	 */
 	public function buildConsequenceSelector( $action, $set, $parameters, $row ) {
 		$config = $this->getConfig();
@@ -893,7 +893,7 @@ class AbuseFilterViewEdit extends AbuseFilterView {
 	/**
 	 * @param string $warnMsg
 	 * @param bool $readOnly
-	 * @return string
+	 * @return \OOUI\FieldLayout
 	 */
 	public function getExistingSelector( $warnMsg, $readOnly = false ) {
 		$existingSelector =

includes/Views/AbuseFilterViewTestBatch.php

@@ -121,7 +121,7 @@ class AbuseFilterViewTestBatch extends AbuseFilterView {
 	}
 
 	/**
-	 * @fixme this is similar to AbuseFilterExaminePager::getQueryInfo
+	 * Loads the revisions and checks the given syntax against them
 	 */
 	public function doTest() {
 		// Quick syntax check.

includes/pagers/AbuseFilterExaminePager.php

@@ -14,7 +14,6 @@ class AbuseFilterExaminePager extends ReverseChronologicalPager {
 	}
 
 	/**
-	 * @fixme this is similar to AbuseFilterViewTestBatch::doTest
 	 * @return array
 	 */
 	public function getQueryInfo() {

includes/pagers/AbuseFilterHistoryPager.php

@@ -1,5 +1,7 @@
 <?php
 
+use MediaWiki\Linker\LinkRenderer;
+
 class AbuseFilterHistoryPager extends TablePager {
 	public $mFilter, $mPage, $mUser;
 
@@ -8,7 +10,7 @@ class AbuseFilterHistoryPager extends TablePager {
 	 * @param string $filter
 	 * @param AbuseFilterViewHistory $page
 	 * @param string $user User name
-	 * @param \MediaWiki\Linker\LinkRenderer $linkRenderer
+	 * @param LinkRenderer $linkRenderer
 	 */
 	public function __construct( $filter, $page, $user, $linkRenderer ) {
 		$this->mFilter = $filter;

includes/parser/AFPToken.php

@@ -54,7 +54,7 @@ class AFPToken {
 
 	/**
 	 * @param string $type
-	 * @param AFPToken|null $value
+	 * @param mixed|null $value
 	 * @param int $pos
 	 */
 	public function __construct( $type = self::TNONE, $value = null, $pos = 0 ) {

includes/parser/AbuseFilterParser.php

@@ -4,7 +4,9 @@ use Wikimedia\Equivset\Equivset;
 use MediaWiki\Logger\LoggerFactory;
 
 class AbuseFilterParser {
-	public $mCode, $mTokens, $mPos, $mCur, $mShortCircuit, $mAllowShort, $mLen;
+	public $mCode, $mTokens, $mPos, $mShortCircuit, $mAllowShort, $mLen;
+	/** @var AFPToken The current token */
+	public $mCur;
 
 	/**
 	 * @var AbuseFilterVariableHolder
@@ -428,7 +430,7 @@ class AbuseFilterParser {
 			$this->move();
 			$r2 = new AFPData();
 
-			// We can go on quickly as either one statement with | is true or on with & is false
+			// We can go on quickly as either one statement with | is true or one with & is false
 			if ( ( $op == '&' && !$result->toBool() ) || ( $op == '|' && $result->toBool() ) ) {
 				$orig = $this->mShortCircuit;
 				$this->mShortCircuit = $this->mAllowShort;
@@ -1014,7 +1016,6 @@ class AbuseFilterParser {
 
 			// Suppress and restore needed per T177744
 			Wikimedia\suppressWarnings();
-
 			$count = preg_match_all( $needle, $haystack );
 			Wikimedia\restoreWarnings();
 
@@ -1079,7 +1080,7 @@ class AbuseFilterParser {
 
 		// Returned array has non-empty positions identical to the ones returned
 		// by the third parameter of a standard preg_match call ($matches in this case).
-		// We want an union with falsy to return a fixed-dimention array.
+		// We want an union with falsy to return a fixed-dimension array.
 		return AFPData::newFromPHPVar( $matches + $falsy );
 	}
 

includes/special/SpecialAbuseLog.php

@@ -614,7 +614,7 @@ class SpecialAbuseLog extends SpecialPage {
 
 	/**
 	 * @param string $id
-	 * @return null
+	 * @return void
 	 */
 	public function showPrivateDetails( $id ) {
 		$lang = $this->getLanguage();
@@ -642,7 +642,7 @@ class SpecialAbuseLog extends SpecialPage {
 		if ( !$this->checkReason( $reason ) ) {
 			$out->addWikiMsg( 'abusefilter-noreason' );
 			$this->showDetails( $id );
-			return false;
+			return;
 		}
 
 		$row = $dbr->selectRow(
@@ -857,7 +857,7 @@ class SpecialAbuseLog extends SpecialPage {
 
 	/**
 	 * @param string|null $filter_id
-	 * @param bool|null $filter_hidden
+	 * @param bool|int|null $filter_hidden
 	 * @return bool
 	 */
 	public static function canSeeDetails( $filter_id = null, $filter_hidden = null ) {

modules/ext.abuseFilter.edit.js

@@ -9,15 +9,13 @@
 ( function ( mw, $, OO ) {
 	'use strict';
 
-	// Filter editor for JS and jQuery handling
-	// @var {jQuery}
+	// @var {jQuery} Filter editor for JS and jQuery handling
 	var $filterBox,
 		// Filter editor for Ace specific functions
 		filterEditor,
-		// Hidden textarea for submitting form
-		// @var {jQuery}
+		// @var {jQuery} Hidden textarea for submitting form
 		$plainTextBox,
-		// Bool to determine what editor to use
+		// @var {boolean} To determine what editor to use
 		useAce = false,
 		// Infused OOUI elements
 		togglePreviewButton,
@@ -42,9 +40,9 @@
 	/**
 	 * Things always needed after syntax checks
 	 *
-	 * @param {string} resultText
+	 * @param {string} resultText The message to show, telling if the syntax is valid
 	 * @param {string} className Class to add
-	 * @param {bool} syntaxOk Is the syntax ok?
+	 * @param {boolean} syntaxOk Is the syntax ok?
 	 */
 	function processSyntaxResultAlways( resultText, className, syntaxOk ) {
 		$.removeSpinner( 'abusefilter-syntaxcheck' );
@@ -130,7 +128,7 @@
 	 * Sends the current filter text to be checked for syntax issues.
 	 *
 	 * @context HTMLElement
-	 * @param {jQuery.Event} e
+	 * @param {jQuery.Event} e The event fired when the function is called
 	 */
 	function doSyntaxCheck() {
 		var filter = $plainTextBox.val(),
@@ -175,7 +173,7 @@
 	 * Fetches a filter from the API and inserts it into the filter box.
 	 *
 	 * @context HTMLElement
-	 * @param {jQuery.Event} e
+	 * @param {jQuery.Event} e The event fired when the function is called
 	 */
 	function fetchFilter() {
 		var filterId = $.trim( $( '#mw-abusefilter-load-filter input' ).val() ),
@@ -284,7 +282,7 @@
 	 * Called if the filter group (#mw-abusefilter-edit-group-input select) is changed.
 	 *
 	 * @context HTMLELement
-	 * @param {jQuery.Event} e
+	 * @param {jQuery.Event} e The event fired when the function is called
 	 */
 	function onFilterGroupChange() {
 		var $afWarnMessageExisting, newVal;
@@ -324,7 +322,7 @@
 	 * Called if the user presses a key in the load filter field
 	 *
 	 * @context HTMLELement
-	 * @param {jQuery.Event} e
+	 * @param {jQuery.Event} e The event fired when the function is called
 	 */
 	function onFilterKeypress( e ) {
 		if ( e.type === 'keypress' && e.which === 13 ) {

modules/ext.abuseFilter.examine.js

@@ -8,14 +8,13 @@
 ( function ( mw, $ ) {
 	'use strict';
 
-	// Syntax result div
-	// @type {jQuery}
+	// @var {jQuery} Syntax result div
 	var $syntaxResult;
 
 	/**
 	 * Processes the results of the filter test
 	 *
-	 * @param {Object} data
+	 * @param {Object} data The response of the API request
 	 */
 	function examinerTestProcess( data ) {
 		var msg, exClass;
@@ -70,7 +69,7 @@
 	 * Tests the filter against an rc event or abuse log entry.
 	 *
 	 * @context HTMLElement
-	 * @param {jQuery.Event} e
+	 * @param {jQuery.Event} e The event fired when the function is called
 	 */
 	function examinerTestFilter() {
 		var filter = $( '#wpTestFilter' ).val(),

modules/ext.abuseFilter.tools.js

@@ -11,7 +11,7 @@
 	/**
 	 * Submits the expression to be evaluated.
 	 * @context HTMLElement
-	 * @param {jQuery.Event} e
+	 * @param {jQuery.Event} e The event fired when the function is called
 	 */
 	function doExprSubmit() {
 		var expr = $( '#wpTestExpr' ).val(),
@@ -39,7 +39,7 @@
 	/**
 	 * Processes the result of the unblocking autopromotions for a user
 	 *
-	 * @param {Object} data
+	 * @param {Object} data The response of the API request
 	 */
 	function processReautoconfirm( data ) {
 		mw.notify(
@@ -52,8 +52,8 @@
 	/**
 	 * Processes the result of the unblocking autopromotions for a user in case of an error
 	 *
-	 * @param {string} errorCode
-	 * @param {Object} data
+	 * @param {string} errorCode Identifier of the error
+	 * @param {Object} data The response of the API request
 	 */
 	function processReautoconfirmFailure( errorCode, data ) {
 		var msg;
@@ -80,8 +80,8 @@
 	/**
 	 * Submits a call to reautoconfirm a user.
 	 * @context HTMLElement
-	 * @param {jQuery.Event} e
-	 * @return {boolean}
+	 * @param {jQuery.Event} e The event fired when the function is called
+	 * @return {boolean} False to prevent form submission
 	 */
 	function doReautoSubmit() {
 		var nameField = OO.ui.infuse( $( '#reautoconfirm-user' ) ),

modules/mode-abusefilter.js

@@ -5,7 +5,6 @@ ace.define( 'ace/mode/abusefilter_highlight_rules', [ 'require', 'exports', 'mod
 	var oop = require( 'ace/lib/oop' ),
 		TextHighlightRules = require( './text_highlight_rules' ).TextHighlightRules,
 		AFHighlightRules = function () {
-
 			var cfg = mw.config.get( 'aceConfig' ),
 				constants = ( 'true|false|null' ),
 				keywordMapper = this.createKeywordMapper(

tests/phpunit/AbuseFilterConsequencesTest.php

@@ -488,7 +488,7 @@ class AbuseFilterConsequencesTest extends MediaWikiTestCase {
 	 *
 	 * @param string $testDescription A short description of the test, used for error reporting
 	 * @param int[] $createIds IDs of the filters to create
-	 * @param array $actionParameters Details of the action we need to execute to trigger filters
+	 * @param array $actionParams Details of the action we need to execute to trigger filters
 	 * @param array $consequences The consequences we're expecting
 	 * @param array $options Further options for the test
 	 * @covers AbuseFilter