StringUtils: Fixup Doxygen warnings

* Code blocks must be indented by 4 spaces (so 5 in total from the star).

* Code blocks are only supported in descriptions, and for some reason the first
  line is separate from the description, so there must be an additional line of
  text between the summary and the code block since it can't be the first thing
  in a description.

* Fix regex confusion with comment syntax due to "/*\/".

To verify these findings, use:

    $ php maintenance/mwdocgen.php --file includes/libs/StringUtils.php

And check the output warnings and generated html pages.

Change-Id: I259b87c0bf3b48a95df0108eb6ee799c25b2853f

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