From: jenkins-bot <jenkins-bot@gerrit.wikimedia.org>
Date: Tue, 24 Nov 2015 19:57:19 +0000 (+0000)
Subject: Merge "StringUtils: Fixup Doxygen warnings"
X-Git-Tag: 1.31.0-rc.0~8886
X-Git-Url: http://git.heureux-cyclage.org/?a=commitdiff_plain;h=8b0a2d80e08895b9d65e2e713cb1c00b99eb268e;hp=33e0c913ceec1635011c7b084237f3185a6b99ba;p=lhc%2Fweb%2Fwiklou.git

Merge "StringUtils: Fixup Doxygen warnings"
---

diff --git a/includes/libs/StringUtils.php b/includes/libs/StringUtils.php
index 11ae0b26f2..c56ed07a88 100644
--- a/includes/libs/StringUtils.php
+++ b/includes/libs/StringUtils.php
@@ -36,16 +36,15 @@ class StringUtils {
 	 * true will skip the use of mb_check_encoding, this is mostly intended for
 	 * unit testing our internal implementation.
 	 *
-	 * @since 1.21
 	 * @note In MediaWiki 1.21, this function did not provide proper UTF-8 validation.
 	 * In particular, the pure PHP code path did not in fact check for overlong forms.
 	 * Beware of this when backporting code to that version of MediaWiki.
 	 *
+	 * @since 1.21
 	 * @param string $value String to check
 	 * @param bool $disableMbstring Whether to use the pure PHP
-	 * implementation instead of trying mb_check_encoding. Intended for unit
-	 * testing. Default: false
-	 *
+	 *  implementation instead of trying mb_check_encoding. Intended for unit
+	 *  testing. Default: false
 	 * @return bool Whether the given $value is a valid UTF-8 encoded string
 	 */
 	static function isUtf8( $value, $disableMbstring = false ) {
@@ -111,21 +110,20 @@ class StringUtils {
 	}
 
 	/**
-	 * Perform an operation equivalent to
+	 * Perform an operation equivalent to `preg_replace()`
 	 *
-	 *     preg_replace( "!$startDelim(.*?)$endDelim!", $replace, $subject );
+	 * Matches this code:
 	 *
-	 * except that it's worst-case O(N) instead of O(N^2)
+	 *     preg_replace( "!$startDelim(.*?)$endDelim!", $replace, $subject );
 	 *
-	 * Compared to delimiterReplace(), this implementation is fast but memory-
-	 * hungry and inflexible. The memory requirements are such that I don't
-	 * recommend using it on anything but guaranteed small chunks of text.
+	 * ..except that it's worst-case O(N) instead of O(N^2). Compared to delimiterReplace(), this
+	 * implementation is fast but memory-hungry and inflexible. The memory requirements are such
+	 * that I don't recommend using it on anything but guaranteed small chunks of text.
 	 *
 	 * @param string $startDelim
 	 * @param string $endDelim
 	 * @param string $replace
 	 * @param string $subject
-	 *
 	 * @return string
 	 */
 	static function hungryDelimiterReplace( $startDelim, $endDelim, $replace, $subject ) {
@@ -144,18 +142,20 @@ class StringUtils {
 	}
 
 	/**
-	 * Perform an operation equivalent to
+	 * Perform an operation equivalent to `preg_replace_callback()`
 	 *
-	 *   preg_replace_callback( "!$startDelim(.*)$endDelim!s$flags", $callback, $subject )
+	 * Matches this code:
 	 *
-	 * This implementation is slower than hungryDelimiterReplace but uses far less
-	 * memory. The delimiters are literal strings, not regular expressions.
+	 *     preg_replace_callback( "!$startDelim(.*)$endDelim!s$flags", $callback, $subject );
 	 *
 	 * If the start delimiter ends with an initial substring of the end delimiter,
 	 * e.g. in the case of C-style comments, the behavior differs from the model
 	 * regex. In this implementation, the end must share no characters with the
-	 * start, so e.g. /*\/ is not considered to be both the start and end of a
-	 * comment. /*\/xy/*\/ is considered to be a single comment with contents /xy/.
+	 * start, so e.g. `/*\/` is not considered to be both the start and end of a
+	 * comment. `/*\/xy/*\/` is considered to be a single comment with contents `/xy/`.
+	 *
+	 * The implementation of delimiterReplaceCallback() is slower than hungryDelimiterReplace()
+	 * but uses far less memory. The delimiters are literal strings, not regular expressions.
 	 *
 	 * @param string $startDelim Start delimiter
 	 * @param string $endDelim End delimiter
@@ -241,14 +241,16 @@ class StringUtils {
 	}
 
 	/**
-	 * Perform an operation equivalent to
+	 * Perform an operation equivalent to `preg_replace()` with flags.
+	 *
+	 * Matches this code:
 	 *
-	 *   preg_replace( "!$startDelim(.*)$endDelim!$flags", $replace, $subject )
+	 *     preg_replace( "!$startDelim(.*)$endDelim!$flags", $replace, $subject );
 	 *
 	 * @param string $startDelim Start delimiter regular expression
 	 * @param string $endDelim End delimiter regular expression
 	 * @param string $replace Replacement string. May contain $1, which will be
-	 *                 replaced by the text between the delimiters
+	 *  replaced by the text between the delimiters
 	 * @param string $subject String to search
 	 * @param string $flags Regular expression flags
 	 * @return string The string with the matches replaced
@@ -262,7 +264,7 @@ class StringUtils {
 
 	/**
 	 * More or less "markup-safe" explode()
-	 * Ignores any instances of the separator inside <...>
+	 * Ignores any instances of the separator inside `<...>`
 	 * @param string $separator
 	 * @param string $text
 	 * @return array
@@ -296,13 +298,12 @@ class StringUtils {
 	static function escapeRegexReplacement( $string ) {
 		$string = str_replace( '\\', '\\\\', $string );
 		$string = str_replace( '$', '\\$', $string );
-
 		return $string;
 	}
 
 	/**
 	 * Workalike for explode() with limited memory usage.
-	 * Returns an Iterator
+	 *
 	 * @param string $separator
 	 * @param string $subject
 	 * @return ArrayIterator|ExplodeIterator