Matěj Suchánek has uploaded a new change for review. ( 
https://gerrit.wikimedia.org/r/330117 )

Change subject: Improve documentation of methods
......................................................................

Improve documentation of methods

Change-Id: I231d6a3e095324ae1509fdf028bcc352148a0dbe
---
M AbuseFilter.hooks.php
M includes/AbuseFilter.class.php
2 files changed, 134 insertions(+), 124 deletions(-)


  git pull ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/AbuseFilter 
refs/changes/17/330117/7

diff --git a/AbuseFilter.hooks.php b/AbuseFilter.hooks.php
index a10552c..ed76687 100644
--- a/AbuseFilter.hooks.php
+++ b/AbuseFilter.hooks.php
@@ -222,10 +222,10 @@
         * @param bool $minoredit
         * @param bool $watchthis
         * @param string $sectionanchor
-        * @param integer $flags
+        * @param int $flags
         * @param Revision $revision
-        * @param $status Status
-        * @param $baseRevId
+        * @param Status $status
+        * @param int $baseRevId
         * @return bool
         */
        public static function onPageContentSaveComplete(
@@ -286,8 +286,8 @@
 
        /**
         * Check if two article objects are identical or have an identical 
WikiPage
-        * @param $page1 Article|WikiPage
-        * @param $page2 Article|WikiPage
+        * @param Article|WikiPage $page1
+        * @param Article|WikiPage $page2
         * @return bool
         */
        protected static function identicalPageObjects( $page1, $page2 ) {
@@ -302,8 +302,8 @@
        }
 
        /**
-        * @param $user
-        * @param $promote
+        * @param User $user
+        * @param array &$promote
         * @return bool
         */
        public static function onGetAutoPromoteGroups( $user, &$promote ) {
@@ -325,6 +325,14 @@
                return true;
        }
 
+       /**
+        * @param Title $oldTitle
+        * @param Title $newTitle
+        * @param User $user
+        * @param string $reason
+        * @param Status $status
+        * @return bool
+        */
        public static function onMovePageCheckPermissions( Title $oldTitle, 
Title $newTitle,
                User $user, $reason, Status $status
        ) {
@@ -371,9 +379,9 @@
        }
 
        /**
-        * @param $user User
-        * @param $message
-        * @param $autocreate bool Indicates whether the account is created 
automatically.
+        * @param User $user
+        * @param Message $message
+        * @param bool $autocreate Indicates whether the account is created 
automatically.
         * @return bool
         * @deprecated AbuseFilterPreAuthenticationProvider will take over this 
functionality
         */
@@ -405,8 +413,8 @@
        }
 
        /**
-        * @param $user User
-        * @param $message
+        * @param User $user
+        * @param Message $message
         * @return bool
         * @deprecated AbuseFilterPreAuthenticationProvider will take over this 
functionality
         */
@@ -415,8 +423,8 @@
        }
 
        /**
-        * @param $user User
-        * @param $message
+        * @param User $user
+        * @param Message $message
         * @return bool
         * @deprecated AbuseFilterPreAuthenticationProvider will take over this 
functionality
         */
@@ -428,7 +436,7 @@
        }
 
        /**
-        * @param $recentChange RecentChange
+        * @param RecentChange $recentChange
         * @return bool
         */
        public static function onRecentChangeSave( $recentChange ) {
@@ -450,7 +458,7 @@
        }
 
        /**
-        * @param array $tags
+        * @param string[] $tags
         * @param bool $enabled
         * @return bool
         */
@@ -502,7 +510,7 @@
        }
 
        /**
-        * @param array $tags
+        * @param string[] $tags
         * @return bool
         */
        public static function onListDefinedTags( array &$tags ) {
@@ -510,7 +518,7 @@
        }
 
        /**
-        * @param array $tags
+        * @param string[] $tags
         * @return bool
         */
        public static function onChangeTagsListActive( array &$tags ) {
@@ -518,7 +526,7 @@
        }
 
        /**
-        * @param $updater DatabaseUpdater
+        * @param DatabaseUpdater|null $updater
         * @throws MWException
         * @return bool
         */
@@ -631,7 +639,7 @@
 
        /**
         * Updater callback to create the AbuseFilter user after the user 
tables have been updated.
-        * @param $updater DatabaseUpdater
+        * @param DatabaseUpdater $updater
         */
        public static function createAbuseFilterUser( $updater ) {
                $username = wfMessage( 'abusefilter-blocker' 
)->inContentLanguage()->text();
diff --git a/includes/AbuseFilter.class.php b/includes/AbuseFilter.class.php
index daf2ae8..f872a27 100644
--- a/includes/AbuseFilter.class.php
+++ b/includes/AbuseFilter.class.php
@@ -16,6 +16,8 @@
        private static $filterCache = [];
 
        public static $condCount = 0;
+
+       /** @var array Map of (action ID => string[]) */
        public static $tagsToSet = array(); // FIXME: avoid global state here
 
        public static $history_mappings = array(
@@ -148,8 +150,8 @@
        public static $editboxName = null;
 
        /**
-        * @param $context IContextSource
-        * @param $pageType
+        * @param IContextSource $context
+        * @param string $pageType
         */
        public static function addNavigationLinks( IContextSource $context, 
$pageType ) {
                $linkDefs = array(
@@ -205,7 +207,7 @@
 
        /**
         * @static
-        * @param  $user User
+        * @param User $user
         * @return AbuseFilterVariableHolder
         */
        public static function generateUserVars( $user ) {
@@ -275,7 +277,7 @@
        }
 
        /**
-        * @param $filter
+        * @param string $filter
         * @return bool
         */
        public static function filterHidden( $filter ) {
@@ -304,7 +306,7 @@
        }
 
        /**
-        * @param $val int
+        * @param int $val
         * @throws MWException
         */
        public static function triggerLimiter( $val = 1 ) {
@@ -323,8 +325,8 @@
        }
 
        /**
-        * @param $title Title
-        * @param $prefix
+        * @param Title|null $title
+        * @param string $prefix
         * @return AbuseFilterVariableHolder
         */
        public static function generateTitleVars( $title, $prefix ) {
@@ -410,9 +412,9 @@
        }
 
        /**
-        * @param $conds
-        * @param $vars
-        * @param $ignoreError bool
+        * @param string $conds
+        * @param AbuseFilterVariableHolder $vars
+        * @param bool $ignoreError
         * @return bool
         * @throws Exception
         */
@@ -448,7 +450,7 @@
        /**
         * Returns an associative array of filters which were tripped
         *
-        * @param $vars AbuseFilterVariableHolder
+        * @param AbuseFilterVariableHolder $vars
         * @param string $group The filter's group (as defined in 
$wgAbuseFilterValidGroups)
         *
         * @return bool[] Map of (integer filter ID => bool)
@@ -522,10 +524,10 @@
 
        /**
         * @static
-        * @param $row
-        * @param $vars
-        * @param $profile bool
-        * @param $prefix string
+        * @param stdClass $row
+        * @param AbuseFilterVariableHolder $vars
+        * @param bool $profile
+        * @param string $prefix
         * @return bool
         */
        public static function checkFilter( $row, $vars, $profile = false, 
$prefix = '' ) {
@@ -571,7 +573,7 @@
        }
 
        /**
-        * @param $filter
+        * @param int $filter
         */
        public static function resetFilterProfile( $filter ) {
                $stash = ObjectCache::getMainStashInstance();
@@ -585,9 +587,9 @@
        }
 
        /**
-        * @param $filter
-        * @param $time
-        * @param $conds
+        * @param int $filter
+        * @param float $time
+        * @param int $conds
         */
        public static function recordProfilingResult( $filter, $time, $conds ) {
                // Defer updates to avoid massive (~1 second) edit time 
increases
@@ -614,7 +616,7 @@
        }
 
        /**
-        * @param $filter
+        * @param string $filter
         * @return array
         */
        public static function getFilterProfile( $filter ) {
@@ -643,7 +645,7 @@
        /**
         * Utility function to decode global-$index to $index. Returns false if 
not global
         *
-        * @param $filter string
+        * @param string $filter
         *
         * @return string|bool
         */
@@ -656,8 +658,8 @@
        }
 
        /**
-        * @param $filters array
-        * @return array
+        * @param string[] $filters
+        * @return array[]
         */
        public static function getConsequencesForFilters( $filters ) {
                $globalFilters = array();
@@ -692,10 +694,10 @@
        }
 
        /**
-        * @param $dbr DatabaseBase
-        * @param $filters array
-        * @param $prefix string
-        * @return array
+        * @param DatabaseBase $dbr
+        * @param string[] $filters
+        * @param string $prefix
+        * @return array[]
         */
        public static function loadConsequencesFromDB( $dbr, $filters, $prefix 
= '' ) {
                $actionsByFilter = array();
@@ -736,13 +738,13 @@
        /**
         * Executes a list of actions.
         *
-        * @param $filters array
-        * @param $title Title
-        * @param $vars AbuseFilterVariableHolder
-        * @param $user User
+        * @param string[] $filters
+        * @param Title $title
+        * @param AbuseFilterVariableHolder $vars
+        * @param User $user
         * @return Status returns the operation's status. $status->isOK() will 
return true if
         *         there were no actions taken, false otherwise. 
$status->getValue() will return
-        *         an array listing the actions taken. $status-getErrors(), 
etc, will provide
+        *         an array listing the actions taken. $status->getErrors() 
etc. will provide
         *         the errors and warnings to be shown to the user to explain 
the actions.
         */
        private static function executeFilterActions( $filters, $title, $vars, 
$user ) {
@@ -870,8 +872,8 @@
        }
 
        /**
-        * @param $vars AbuseFilterVariableHolder
-        * @param $title Title
+        * @param AbuseFilterVariableHolder $vars
+        * @param Title $title
         * @param string $group The filter's group (as defined in 
$wgAbuseFilterValidGroups)
         * @param User $user The user performing the action; defaults to $wgUser
         * @param string $mode Use 'execute' to run filters and log or 'stash' 
to only cache matches
@@ -1028,10 +1030,10 @@
        }
 
        /**
-        * @param $actions_taken
-        * @param $log_template
-        * @param $action
-        * @param $vars AbuseFilterVariableHolder
+        * @param array[] $actions_taken
+        * @param array $log_template
+        * @param string $action
+        * @param AbuseFilterVariableHolder $vars
         * @param string $group The filter's group (as defined in 
$wgAbuseFilterValidGroups)
         * @return mixed
         */
@@ -1198,10 +1200,10 @@
         * Store a var dump to External Storage or the text table
         * Some of this code is stolen from Revision::insertOn and friends
         *
-        * @param $vars AbuseFilterVariableHolder
-        * @param $global bool
+        * @param AbuseFilterVariableHolder $vars
+        * @param bool $global
         *
-        * @return int
+        * @return int|null
         */
        public static function storeVarDump( $vars, $global = false ) {
                global $wgCompressRevisions;
@@ -1319,13 +1321,13 @@
        }
 
        /**
-        * @param $action string
-        * @param $parameters array
-        * @param $title Title
-        * @param $vars AbuseFilterVariableHolder
-        * @param $rule_desc
-        * @param $rule_number int|string
-        * @param $user User
+        * @param string $action
+        * @param array $parameters
+        * @param Title $title
+        * @param AbuseFilterVariableHolder $vars
+        * @param string $rule_desc
+        * @param int|string $rule_number
+        * @param User $user
         *
         * @return array|null a message describing the action that was taken,
         *         or null if no action was taken. The message is given as an 
array
@@ -1557,11 +1559,11 @@
        /**
         * @param $throttleId
         * @param $types
-        * @param $title
-        * @param $rateCount
-        * @param $ratePeriod
-        * @param $global bool
-        * @param $user User
+        * @param Title $title
+        * @param string $rateCount
+        * @param string $ratePeriod
+        * @param bool $global
+        * @param User $user
         * @return bool
         */
        private static function isThrottled( $throttleId, $types, $title, 
$rateCount,
@@ -1595,9 +1597,9 @@
        }
 
        /**
-        * @param $type
-        * @param $title Title
-        * @param $user User
+        * @param string $type
+        * @param Title $title
+        * @param User $user
         * @return int|string
         */
        private static function throttleIdentifier( $type, $title, $user ) {
@@ -1634,11 +1636,11 @@
 
        /**
         * @param $throttleId
-        * @param $type
-        * @param $title Title
-        * @param $global bool
-        * @param $user User
-        * @return String
+        * @param string $type
+        * @param Title $title
+        * @param bool $global
+        * @param User $user
+        * @return string
         */
        private static function throttleKey( $throttleId, $type, $title, 
$global = false, $user ) {
                $types = explode( ',', $type );
@@ -1666,7 +1668,7 @@
 
        /**
         * @param string $group The filter's group (as defined in 
$wgAbuseFilterValidGroups)
-        * @return String
+        * @return string
         */
        public static function getGlobalRulesKey( $group ) {
                global $wgAbuseFilterIsCentral, $wgAbuseFilterCentralDB;
@@ -1684,8 +1686,8 @@
        }
 
        /**
-        * @param $user User
-        * @return String
+        * @param User $user
+        * @return string
         */
        public static function autoPromoteBlockKey( $user ) {
                return wfMemcKey( 'abusefilter', 'block-autopromote', 
$user->getId() );
@@ -1693,7 +1695,7 @@
 
        /**
         * Update statistics, and disable filters which are over-blocking.
-        * @param $filters
+        * @param bool[] $filters
         * @param string $group The filter's group (as defined in 
$wgAbuseFilterValidGroups)
         */
        public static function recordStats( $filters, $group = 'default' ) {
@@ -1735,8 +1737,8 @@
 
        /**
         * @param string $group The filter's group (as defined in 
$wgAbuseFilterValidGroups)
-        * @param $filters
-        * @param $total
+        * @param string[] $filters
+        * @param int $total
         */
        public static function checkEmergencyDisable( $group, $filters, $total 
) {
                global $wgAbuseFilterEmergencyDisableThreshold, 
$wgAbuseFilterEmergencyDisableCount,
@@ -1801,23 +1803,23 @@
        }
 
        /**
-        * @return String
+        * @return string
         */
        public static function filterLimitReachedKey() {
                return wfMemcKey( 'abusefilter', 'stats', 'overflow' );
        }
 
        /**
-        * @param string $group The filter's group (as defined in 
$wgAbuseFilterValidGroups)
-        * @return String
+        * @param string|null $group The filter's group (as defined in 
$wgAbuseFilterValidGroups)
+        * @return string
         */
        public static function filterUsedKey( $group = null ) {
                return wfMemcKey( 'abusefilter', 'stats', 'total', $group );
        }
 
        /**
-        * @param $filter
-        * @return String
+        * @param string|null $filter
+        * @return string
         */
        public static function filterMatchesKey( $filter = null ) {
                return wfMemcKey( 'abusefilter', 'stats', 'matches', $filter );
@@ -1861,11 +1863,11 @@
        }
 
        /**
-        * @param $rules String
-        * @param $textName String
-        * @param $addResultDiv Boolean
-        * @param $canEdit Boolean
-        * @param $context IContextSource
+        * @param string $rules
+        * @param string $textName
+        * @param bool $addResultDiv
+        * @param bool $canEdit
+        * @param IContextSource $context
         * @return string
         */
        public static function buildEditBox( $rules, $textName = 
'wpFilterRules', $addResultDiv = true,
@@ -1947,8 +1949,8 @@
         * Each version is expected to be an array( $row, $actions )
         * Returns an array of fields that are different.
         *
-        * @param $version_1
-        * @param $version_2
+        * @param array $version_1
+        * @param array $version_2
         *
         * @return array
         */
@@ -1995,7 +1997,7 @@
        }
 
        /**
-        * @param $row
+        * @param stdClass $row
         * @return array
         */
        static function translateFromHistory( $row ) {
@@ -2035,8 +2037,8 @@
        }
 
        /**
-        * @param $action string
-        * @return String
+        * @param string $action
+        * @return string
         */
        static function getActionDisplay( $action ) {
                // Give grep a chance to find the usages:
@@ -2050,7 +2052,7 @@
        }
 
        /**
-        * @param $row
+        * @param stdClass $row
         * @return AbuseFilterVariableHolder|null
         */
        public static function getVarsFromRCRow( $row ) {
@@ -2073,7 +2075,7 @@
        }
 
        /**
-        * @param $row
+        * @param stdClass $row
         * @return AbuseFilterVariableHolder
         */
        public static function getCreateVarsFromRCRow( $row ) {
@@ -2096,7 +2098,7 @@
        }
 
        /**
-        * @param $row
+        * @param stdClass $row
         * @return AbuseFilterVariableHolder
         */
        public static function getEditVarsFromRCRow( $row ) {
@@ -2134,7 +2136,7 @@
        }
 
        /**
-        * @param $row
+        * @param stdClass $row
         * @return AbuseFilterVariableHolder
         */
        public static function getMoveVarsFromRCRow( $row ) {
@@ -2164,7 +2166,7 @@
 
        /**
         * @param Title $title
-        * @param null|Page $page
+        * @param Page|null $page
         * @return AbuseFilterVariableHolder
         */
        public static function getEditVars( $title, Page $page = null ) {
@@ -2243,7 +2245,7 @@
        }
 
        /**
-        * @param AbuseFilterVariableHolder $vars
+        * @param AbuseFilterVariableHolder|array $vars
         * @param IContextSource $context
         * @return string
         */
@@ -2310,12 +2312,12 @@
 
        /**
         * @param $page
-        * @param $type
-        * @param $title Title
-        * @param $sk Skin
-        * @param $args array
-        * @param $filterWikilinks bool
-        * @return String
+        * @param string $type
+        * @param Title $title
+        * @param Skin $sk
+        * @param array $args
+        * @param bool $filterWikilinks
+        * @return string
         */
        static function modifyActionText( $page, $type, $title, $sk, $args, 
$filterWikilinks ) {
                list( $history_id, $filter_id ) = $args;
@@ -2341,9 +2343,9 @@
        }
 
        /**
-        * @param $action
-        * @param $parameters
-        * @return String
+        * @param string $action
+        * @param string[] $parameters
+        * @return string
         */
        static function formatAction( $action, $parameters ) {
                /** @var $wgLang Language */
@@ -2360,7 +2362,7 @@
        }
 
        /**
-        * @param $value array
+        * @param string $value
         * @return string
         */
        static function formatFlags( $value ) {
@@ -2376,8 +2378,8 @@
        }
 
        /**
-        * @param $filterID
-        * @return bool|mixed|string
+        * @param string $filterID
+        * @return string
         */
        static function getGlobalFilterDescription( $filterID ) {
                global $wgAbuseFilterCentralDB;
@@ -2400,7 +2402,7 @@
         * Gives either the user-specified name for a group,
         * or spits the input back out
         * @param string $group The filter's group (as defined in 
$wgAbuseFilterValidGroups)
-        * @return String A name for that filter group, or the input.
+        * @return string A name for that filter group, or the input.
         */
        static function nameGroup( $group ) {
                // Give grep a chance to find the usages: 
abusefilter-group-default
@@ -2464,7 +2466,7 @@
                }
 
                if ( is_string( $text ) ) {
-                       // bug 20310
+                       // T22310
                        // XXX: Is this really needed? Should we rather apply 
PST?
                        $text = str_replace( "\r\n", "\n", $text );
                } else {
@@ -2477,8 +2479,8 @@
        /*
         * Get the history ID of the first change to a given filter
         *
-        * @param $filterId integer: Filter id
-        * @return integer|bool
+        * @param int $filterId Filter id
+        * @return int
         */
        public static function getFirstFilterChange( $filterID ) {
                static $firstChanges = array();

-- 
To view, visit https://gerrit.wikimedia.org/r/330117
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings

Gerrit-MessageType: newchange
Gerrit-Change-Id: I231d6a3e095324ae1509fdf028bcc352148a0dbe
Gerrit-PatchSet: 7
Gerrit-Project: mediawiki/extensions/AbuseFilter
Gerrit-Branch: master
Gerrit-Owner: Matěj Suchánek <matejsuchane...@gmail.com>
Gerrit-Reviewer: jenkins-bot <>

_______________________________________________
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits

Reply via email to