Merge "StringUtils: Fixup Doxygen warnings"

diff --git a/includes/libs/StringUtils.php b/includes/libs/StringUtils.php
index 11ae0b2..c56ed07 100644 (file)
--- 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