Thiemo Mättig (WMDE) has uploaded a new change for review.
https://gerrit.wikimedia.org/r/120850
Change subject: Fix/update inline documentations in GlobalFunctions
......................................................................
Fix/update inline documentations in GlobalFunctions
Mainly fixed PHPDoc comments that are highlighted by PHPStorm as
being wrong or incomplete.
* Fix some wrong inline documentations, e.g. wrong @return types.
* Used the style suggested by the Doxygen and phpDocumentor
documentations: @param type [$optional,...]
* Doxygen and phpDocumentor suggest the order: @param type $var
* Avoid unclear "varargs" and "mixed" if possible.
* Lowercase "array" and such, they are no classes.
Change-Id: Iff16e05fed6652cefec29e3d254807f52d84c9ab
---
M includes/GlobalFunctions.php
1 file changed, 130 insertions(+), 113 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/mediawiki/core
refs/changes/50/120850/1
diff --git a/includes/GlobalFunctions.php b/includes/GlobalFunctions.php
index f0b0a8d..14336fe 100644
--- a/includes/GlobalFunctions.php
+++ b/includes/GlobalFunctions.php
@@ -177,11 +177,12 @@
* XXX: will not darn your socks for you.
*
* @deprecated since 1.22; use array_replace()
- * @param $array1 Array
- * @param [$array2, [...]] Arrays
- * @return Array
+ *
+ * @param array $array1 Initial array to merge.
+ * @param array [$array2,...] Variable list of arrays to merge.
+ * @return array
*/
-function wfArrayMerge( $array1/* ... */ ) {
+function wfArrayMerge( $array1 /*...*/ ) {
wfDeprecated( __FUNCTION__, '1.22' );
$args = func_get_args();
$args = array_reverse( $args, true );
@@ -207,8 +208,9 @@
* array( 'x' ),
* array( 'y' )
* )
- * @param varargs
- * @return Array
+ *
+ * @param array [$array1,...]
+ * @return array
*/
function wfMergeErrorArrays( /*...*/ ) {
$args = func_get_args();
@@ -407,7 +409,7 @@
* arrays. Of course, keys and values are urldecode()d.
*
* @param string $query query string
- * @return array Array version of input
+ * @return string[] Array version of input
*/
function wfCgiToArray( $query ) {
if ( isset( $query[0] ) && $query[0] == '?' ) {
@@ -452,8 +454,8 @@
* Append a query string to an existing URL, which may or may not already
* have query string parameters already. If so, they will be combined.
*
- * @param $url String
- * @param $query Mixed: string or associative array
+ * @param string $url
+ * @param string|string[] $query String or associative array
* @return string
*/
function wfAppendQuery( $url, $query ) {
@@ -750,7 +752,7 @@
* 3) Adds a "delimiter" element to the array, either '://', ':' or '//' (see
(2)).
*
* @param string $url a URL to parse
- * @return Array: bits of the URL in an associative array, per PHP docs
+ * @return string[] Bits of the URL in an associative array, per PHP docs
*/
function wfParseUrl( $url ) {
global $wgUrlProtocols; // Allow all protocols defined in
DefaultSettings/LocalSettings.php
@@ -1381,12 +1383,15 @@
*
* This function replaces all old wfMsg* functions.
*
- * @param $key \string Message key.
- * Varargs: normal message parameters.
+ * @param string $key Message key
+ * @param mixed [$params,...] Normal message parameters
* @return Message
+ *
* @since 1.17
+ *
+ * @see Message::__construct
*/
-function wfMessage( $key /*...*/) {
+function wfMessage( $key /*...*/ ) {
$params = func_get_args();
array_shift( $params );
if ( isset( $params[0] ) && is_array( $params[0] ) ) {
@@ -1399,9 +1404,13 @@
* This function accepts multiple message keys and returns a message instance
* for the first message which is non-empty. If all messages are empty then an
* instance of the first message key is returned.
- * @param varargs: message keys
+ *
+ * @param string|string[] [$keys,...] Message keys
* @return Message
+ *
* @since 1.18
+ *
+ * @see Message::newFallbackSequence
*/
function wfMessageFallback( /*...*/ ) {
$args = func_get_args();
@@ -1520,11 +1529,11 @@
* @deprecated since 1.18
*
* @param string $key key to get.
- * @param $args
- * @param $useDB Boolean
- * @param $forContent Mixed: Language code, or false for user lang, true for
content lang.
- * @param $transform Boolean: Whether or not to transform the message.
- * @return String: the requested message.
+ * @param array $args
+ * @param bool $useDB
+ * @param string|bool $forContent Language code, or false for user lang, true
for content lang.
+ * @param bool $transform Whether or not to transform the message.
+ * @return string The requested message.
*/
function wfMsgReal( $key, $args, $useDB = true, $forContent = false,
$transform = true ) {
wfDeprecated( __METHOD__, '1.21' );
@@ -1541,11 +1550,11 @@
*
* @deprecated since 1.18
*
- * @param $key String
- * @param $useDB Bool
- * @param string $langCode Code of the language to get the message for, or
+ * @param string $key
+ * @param bool $useDB
+ * @param string|bool $langCode Code of the language to get the message for, or
* behaves as a content language switch if it is a boolean.
- * @param $transform Boolean: whether to parse magic words, etc.
+ * @param bool $transform Whether to parse magic words, etc.
* @return string
*/
function wfMsgGetKey( $key, $useDB = true, $langCode = false, $transform =
true ) {
@@ -1566,8 +1575,8 @@
/**
* Replace message parameter keys on the given formatted output.
*
- * @param $message String
- * @param $args Array
+ * @param string $message
+ * @param array $args
* @return string
* @private
*/
@@ -1600,8 +1609,8 @@
*
* @deprecated since 1.18
*
- * @param $key String
- * @param string ... parameters
+ * @param string $key
+ * @param string [$args,...] Parameters
* @return string
*/
function wfMsgHtml( $key ) {
@@ -1621,8 +1630,8 @@
*
* @deprecated since 1.18
*
- * @param $key String
- * @param string ... parameters
+ * @param string $key
+ * @param string [$args,...] Parameters
* @return string
*/
function wfMsgWikiHtml( $key ) {
@@ -1738,8 +1747,8 @@
*
* @deprecated since 1.18. Use Message::isDisabled().
*
- * @param $key String: the message key looked up
- * @return Boolean True if the message *doesn't* exist.
+ * @param string $key The message key looked up
+ * @return bool True if the message *doesn't* exist.
*/
function wfEmptyMsg( $key ) {
wfDeprecated( __METHOD__, '1.21' );
@@ -1961,9 +1970,9 @@
/**
* @todo document
*
- * @param $offset Int
- * @param $limit Int
- * @return String
+ * @param int $offset
+ * @param int $limit
+ * @return string
*/
function wfShowingResults( $offset, $limit ) {
return wfMessage( 'showingresults' )->numParams( $limit, $offset + 1
)->parse();
@@ -1972,12 +1981,12 @@
/**
* Generate (prev x| next x) (20|50|100...) type links for paging
*
- * @param $offset String
- * @param $limit Integer
- * @param $link String
+ * @param string $offset
+ * @param int $limit
+ * @param string $link
* @param string $query optional URL query parameter string
* @param bool $atend optional param for specified if this is the last page
- * @return String
+ * @return string
* @deprecated in 1.19; use Language::viewPrevNext() instead
*/
function wfViewPrevNext( $offset, $limit, $link, $query = '', $atend = false )
{
@@ -2003,7 +2012,7 @@
* @todo document
* @todo FIXME: We may want to blacklist some broken browsers
*
- * @param $force Bool
+ * @param bool $force
* @return bool Whereas client accept gzip compression
*/
function wfClientAcceptsGzip( $force = false ) {
@@ -2255,9 +2264,9 @@
* Converts an Accept-* header into an array mapping string values to quality
* factors
*
- * @param $accept String
+ * @param string $accept
* @param string $def default
- * @return Array
+ * @return float[]
*/
function wfAcceptToPrefs( $accept, $def = '*/*' ) {
# No arg means accept anything (per HTTP spec)
@@ -2290,8 +2299,8 @@
* Returns the matching MIME type (or wildcard) if a match, otherwise
* NULL if no match.
*
- * @param $type String
- * @param $avail Array
+ * @param string $type
+ * @param array $avail
* @return string
* @private
*/
@@ -2474,9 +2483,9 @@
* Return a formatted timestamp, or null if input is null.
* For dealing with nullable timestamp columns in the database.
*
- * @param $outputtype Integer
- * @param $ts String
- * @return String
+ * @param int $outputtype
+ * @param string $ts
+ * @return string
*/
function wfTimestampOrNull( $outputtype = TS_UNIX, $ts = null ) {
if ( is_null( $ts ) ) {
@@ -2499,7 +2508,7 @@
/**
* Check if the operating system is Windows
*
- * @return Bool: true if it's Windows, False otherwise.
+ * @return bool True if it's Windows, false otherwise.
*/
function wfIsWindows() {
static $isWindows = null;
@@ -2512,7 +2521,7 @@
/**
* Check if we are running under HHVM
*
- * @return Bool
+ * @return bool
*/
function wfIsHHVM() {
return defined( 'HHVM_VERSION' );
@@ -2521,8 +2530,8 @@
/**
* Swap two variables
*
- * @param $x Mixed
- * @param $y Mixed
+ * @param mixed $x
+ * @param mixed $y
*/
function swap( &$x, &$y ) {
$z = $x;
@@ -2539,7 +2548,7 @@
* NOTE: When possible, use instead the tmpfile() function to create
* temporary files to avoid race conditions on file creation, etc.
*
- * @return String
+ * @return string
*/
function wfTempDir() {
global $wgTmpDirectory;
@@ -2562,7 +2571,7 @@
* Make directory, and make all parent directories if they don't exist
*
* @param string $dir full path to directory to create
- * @param $mode Integer: chmod value to use, default is $wgDirectoryMode
+ * @param int $mode Chmod value to use, default is $wgDirectoryMode
* @param string $caller optional caller param for debugging.
* @throws MWException
* @return bool
@@ -2629,10 +2638,10 @@
}
/**
- * @param $nr Mixed: the number to format
- * @param $acc Integer: the number of digits after the decimal point, default 2
- * @param $round Boolean: whether or not to round the value, default true
- * @return float
+ * @param number $nr The number to format
+ * @param int $acc The number of digits after the decimal point, default 2
+ * @param bool $round Whether or not to round the value, default true
+ * @return string
*/
function wfPercent( $nr, $acc = 2, $round = true ) {
$ret = sprintf( "%.${acc}f", $nr );
@@ -2659,8 +2668,8 @@
*
* I frickin' hate PHP... :P
*
- * @param $setting String
- * @return Bool
+ * @param string $setting
+ * @return bool
*/
function wfIniGetBool( $setting ) {
$val = strtolower( ini_get( $setting ) );
@@ -2679,10 +2688,10 @@
* Also fixes the locale problems on Linux in PHP 5.2.6+ (bug backported to
* earlier distro releases of PHP)
*
- * @param varargs
- * @return String
+ * @param string [$args,...]
+ * @return string
*/
-function wfEscapeShellArg() {
+function wfEscapeShellArg( /*...*/ ) {
wfInitShellLocale();
$args = func_get_args();
@@ -2739,6 +2748,7 @@
/**
* Check if wfShellExec() is effectively disabled via php.ini config
+ *
* @return bool|string False or one of (safemode,disabled)
* @since 1.22
*/
@@ -2765,6 +2775,7 @@
/**
* Execute a shell command, with time and memory limits mirrored from the PHP
* configuration if supported.
+ *
* @param string $cmd Command line, properly escaped for shell.
* @param &$retval null|Mixed optional, will receive the program's exit code.
* (non-zero is usually failure). If there is an error from
@@ -3027,6 +3038,7 @@
/**
* Alias to wfShellWikiCmd()
+ *
* @see wfShellWikiCmd()
*/
function wfShellMaintenanceCmd( $script, array $parameters = array(), array
$options = array() ) {
@@ -3037,12 +3049,13 @@
* Generate a shell-escaped command line string to run a MediaWiki cli script.
* Note that $parameters should be a flat array and an option with an argument
* should consist of two consecutive items in the array (do not use "--option
value").
+ *
* @param string $script MediaWiki cli script path
* @param array $parameters Arguments and options to the script
* @param array $options Associative array of options:
* 'php': The path to the php executable
* 'wrapper': Path to a PHP wrapper to handle the maintenance
script
- * @return Array
+ * @return string
*/
function wfShellWikiCmd( $script, array $parameters = array(), array $options
= array() ) {
global $wgPhpCli;
@@ -3062,11 +3075,11 @@
* wfMerge attempts to merge differences between three texts.
* Returns true for a clean merge and false for failure or a conflict.
*
- * @param $old String
- * @param $mine String
- * @param $yours String
- * @param $result String
- * @return Bool
+ * @param string $old
+ * @param string $mine
+ * @param string $yours
+ * @param string $result
+ * @return bool
*/
function wfMerge( $old, $mine, $yours, &$result ) {
global $wgDiff3;
@@ -3144,7 +3157,7 @@
* @param string $before the text before the changes.
* @param string $after the text after the changes.
* @param string $params command-line options for the diff command.
- * @return String: unified diff of $before and $after
+ * @return string Unified diff of $before and $after
*/
function wfDiff( $before, $after, $params = '-u' ) {
if ( $before == $after ) {
@@ -3221,7 +3234,7 @@
*
* @see perldoc -f use
*
- * @param $req_ver Mixed: the version to check, can be a string, an integer, or
+ * @param string|number $req_ver The version to check, can be a string, an
integer, or
* a float
* @throws MWException
*/
@@ -3251,7 +3264,7 @@
*
* @see perldoc -f use
*
- * @param $req_ver Mixed: the version to check, can be a string, an integer, or
+ * @param string|number $req_ver The version to check, can be a string, an
integer, or
* a float
* @throws MWException
*/
@@ -3271,9 +3284,9 @@
* PHP's basename() only considers '\' a pathchar on Windows and Netware.
* We'll consider it so always, as we don't want '\s' in our Unix paths either.
*
- * @param $path String
+ * @param string $path
* @param string $suffix to remove if present
- * @return String
+ * @return string
*/
function wfBaseName( $path, $suffix = '' ) {
if ( $suffix == '' ) {
@@ -3297,7 +3310,7 @@
*
* @param string $path absolute destination path including target filename
* @param string $from Absolute source path, directory only
- * @return String
+ * @return string
*/
function wfRelativePath( $path, $from ) {
// Normalize mixed input on Windows...
@@ -3443,6 +3456,7 @@
/**
* Check if there is sufficient entropy in php's built-in session generation
+ *
* @return bool true = there is sufficient entropy
*/
function wfCheckEntropy() {
@@ -3480,6 +3494,7 @@
/**
* Reset the session_id
+ *
* @since 1.22
*/
function wfResetSessionID() {
@@ -3501,7 +3516,7 @@
/**
* Initialise php session
*
- * @param $sessionId Bool
+ * @param bool $sessionId
*/
function wfSetupSession( $sessionId = false ) {
global $wgSessionsInMemcached, $wgSessionsInObjectCache, $wgCookiePath,
$wgCookieDomain,
@@ -3537,8 +3552,8 @@
/**
* Get an object from the precompiled serialized directory
*
- * @param $name String
- * @return Mixed: the variable on success, false on failure
+ * @param string $name
+ * @return mixed The variable on success, false on failure
*/
function wfGetPrecompiledData( $name ) {
global $IP;
@@ -3556,10 +3571,10 @@
/**
* Get a cache key
*
- * @param varargs
- * @return String
+ * @param string [$args,...]
+ * @return string
*/
-function wfMemcKey( /*... */ ) {
+function wfMemcKey( /*...*/ ) {
global $wgCachePrefix;
$prefix = $wgCachePrefix === false ? wfWikiID() : $wgCachePrefix;
$args = func_get_args();
@@ -3571,12 +3586,12 @@
/**
* Get a cache key for a foreign DB
*
- * @param $db String
- * @param $prefix String
- * @param varargs String
- * @return String
+ * @param string $db
+ * @param string $prefix
+ * @param string [$args,...]
+ * @return string
*/
-function wfForeignMemcKey( $db, $prefix /*, ... */ ) {
+function wfForeignMemcKey( $db, $prefix /*...*/ ) {
$args = array_slice( func_get_args(), 2 );
if ( $prefix ) {
$key = "$db-$prefix:" . implode( ':', $args );
@@ -3590,7 +3605,7 @@
* Get an ASCII string identifying this wiki
* This is used as a prefix in memcached keys
*
- * @return String
+ * @return string
*/
function wfWikiID() {
global $wgDBprefix, $wgDBname;
@@ -3604,7 +3619,7 @@
/**
* Split a wiki ID into DB name and table prefix
*
- * @param $wiki String
+ * @param string $wiki
*
* @return array
*/
@@ -3619,15 +3634,15 @@
/**
* Get a Database object.
*
- * @param $db Integer: index of the connection to get. May be DB_MASTER for the
+ * @param int $db Index of the connection to get. May be DB_MASTER for the
* master (for write queries), DB_SLAVE for potentially lagged read
* queries, or an integer >= 0 for a particular server.
*
- * @param $groups Mixed: query groups. An array of group names that this query
+ * @param string|string[] $groups Query groups. An array of group names that
this query
* belongs to. May contain a single string if the query is only
* in one group.
*
- * @param string $wiki the wiki ID, or false for the current wiki
+ * @param string|bool $wiki The wiki ID, or false for the current wiki
*
* Note: multiple calls to wfGetDB(DB_SLAVE) during the course of one request
* will always return the same object, unless the underlying connection or load
@@ -3645,7 +3660,7 @@
/**
* Get a load balancer object.
*
- * @param string $wiki wiki ID, or false for the current wiki
+ * @param string|bool $wiki wiki ID, or false for the current wiki
* @return LoadBalancer
*/
function wfGetLB( $wiki = false ) {
@@ -3689,7 +3704,7 @@
* Get an object referring to a locally registered file.
* Returns a valid placeholder object if the file does not exist.
*
- * @param $title Title|String
+ * @param Title|string $title
* @return LocalFile|null A File, or null if passed an invalid Title
*/
function wfLocalFile( $title ) {
@@ -3699,7 +3714,7 @@
/**
* Should low-performance queries be disabled?
*
- * @return Boolean
+ * @return bool
* @codeCoverageIgnore
*/
function wfQueriesMustScale() {
@@ -3716,7 +3731,7 @@
* except for 'index' and 'load' which use $wgScript/$wgLoadScript
*
* @param string $script script filename, sans extension
- * @return String
+ * @return string
*/
function wfScript( $script = 'index' ) {
global $wgScriptPath, $wgScriptExtension, $wgScript, $wgLoadScript;
@@ -3756,8 +3771,8 @@
* Convenience function converts boolean values into "true"
* or "false" (string) values
*
- * @param $value Boolean
- * @return String
+ * @param bool $value
+ * @return string
*/
function wfBoolToStr( $value ) {
return $value ? 'true' : 'false';
@@ -3780,7 +3795,7 @@
* a no-op if there are no slaves.
*
* @param int|bool $maxLag (deprecated)
- * @param mixed $wiki Wiki identifier accepted by wfGetLB
+ * @param string|bool $wiki Wiki identifier accepted by wfGetLB
* @param string|bool $cluster Cluster name accepted by LBFactory. Default:
false.
*/
function wfWaitForSlaves( $maxLag = false, $wiki = false, $cluster = false ) {
@@ -3804,14 +3819,15 @@
}
/**
- * Count down from $n to zero on the terminal, with a one-second pause
+ * Count down from $seconds to zero on the terminal, with a one-second pause
* between showing each number. For use in command-line scripts.
+ *
* @codeCoverageIgnore
- * @param $n int
+ * @param int $seconds
*/
-function wfCountDown( $n ) {
- for ( $i = $n; $i >= 0; $i-- ) {
- if ( $i != $n ) {
+function wfCountDown( $seconds ) {
+ for ( $i = $seconds; $i >= 0; $i-- ) {
+ if ( $i != $seconds ) {
echo str_repeat( "\x08", strlen( $i + 1 ) );
}
echo $i;
@@ -3828,8 +3844,8 @@
* Additional characters can be defined in $wgIllegalFileChars (see bug 20489)
* By default, $wgIllegalFileChars = ':'
*
- * @param $name Mixed: filename to process
- * @return String
+ * @param string $name Filename to process
+ * @return string
*/
function wfStripIllegalFilenameChars( $name ) {
global $wgIllegalFileChars;
@@ -3846,7 +3862,7 @@
/**
* Set PHP's memory limit to the larger of php.ini or $wgMemoryLimit;
*
- * @return Integer value memory was set to.
+ * @return int Value the memory limit was set to.
*/
function wfMemoryLimit() {
global $wgMemoryLimit;
@@ -3873,8 +3889,8 @@
/**
* Converts shorthand byte notation to integer form
*
- * @param $string String
- * @return Integer
+ * @param string $string
+ * @return int
*/
function wfShorthandToInteger( $string = '' ) {
$string = trim( $string );
@@ -3905,7 +3921,7 @@
* See unit test for examples.
*
* @param string $code The language code.
- * @return String: The language code which complying with BCP 47 standards.
+ * @return string The language code which complying with BCP 47 standards.
*/
function wfBCP47( $code ) {
$codeSegment = explode( '-', $code );
@@ -3986,7 +4002,7 @@
* @param array $args parameters passed to hook functions
* @param string|null $deprecatedVersion optionally mark hook as deprecated
with version number
*
- * @return Boolean True if no handler aborted the hook
+ * @return bool True if no handler aborted the hook
*/
function wfRunHooks( $event, array $args = array(), $deprecatedVersion = null
) {
return Hooks::run( $event, $args, $deprecatedVersion );
@@ -3996,8 +4012,8 @@
* Wrapper around php's unpack.
*
* @param string $format The format string (See php's docs)
- * @param $data: A binary string of binary data
- * @param $length integer or false: The minimum length of $data. This is to
+ * @param string $data A binary string of binary data
+ * @param int|bool $length The minimum length of $data or false. This is to
* prevent reading beyond the end of $data. false to disable the check.
*
* Also be careful when using this function to read unsigned 32 bit integer
@@ -4038,7 +4054,7 @@
* i.e. articles where the image may occur inline.
*
* @param string $name the image name to check
- * @param $contextTitle Title|bool the page on which the image occurs, if known
+ * @param Title|bool $contextTitle The page on which the image occurs, if known
* @param string $blacklist wikitext of a file blacklist
* @return bool
*/
@@ -4140,7 +4156,7 @@
* Useful to tell if X-Forwarded-For data is possibly bogus.
* Squid cache servers for the site are whitelisted.
*
- * @param $ip String
+ * @param string $ip
* @return bool
*/
function wfIsTrustedProxy( $ip ) {
@@ -4151,7 +4167,8 @@
/**
* Checks if an IP matches a proxy we've configured.
- * @param $ip String
+ *
+ * @param string $ip
* @return bool
* @since 1.23 Supports CIDR ranges in $wgSquidServersNoPurge
*/
--
To view, visit https://gerrit.wikimedia.org/r/120850
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Iff16e05fed6652cefec29e3d254807f52d84c9ab
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/core
Gerrit-Branch: master
Gerrit-Owner: Thiemo Mättig (WMDE) <thiemo.maet...@wikimedia.de>
_______________________________________________
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
