Various documentation updates for includes/parser/

Change-Id: I16dd3a792cc83f8c80b3652d42c055730f6d177a

diff --git a/includes/parser/CoreParserFunctions.php b/includes/parser/CoreParserFunctions.php
index 8d52a5b..3425b6b 100644 (file)
--- a/includes/parser/CoreParserFunctions.php
+++ b/includes/parser/CoreParserFunctions.php
@@ -194,7 +194,7 @@ class CoreParserFunctions {
        /**
         * @param Parser $parser
         * @param string $s
-        * @return
+        * @return string
         */
        static function lc( $parser, $s = '' ) {
                global $wgContLang;
@@ -204,7 +204,7 @@ class CoreParserFunctions {
        /**
         * @param Parser $parser
         * @param string $s
-        * @return
+        * @return string
         */
        static function uc( $parser, $s = '' ) {
                global $wgContLang;
@@ -291,7 +291,7 @@ class CoreParserFunctions {
         * @param Parser $parser
         * @param string $case
         * @param string $word
-        * @return
+        * @return string
         */
        static function grammar( $parser, $case = '', $word = '' ) {
                $word = $parser->killMarkers( $word );
@@ -301,7 +301,7 @@ class CoreParserFunctions {
        /**
         * @param Parser $parser
         * @param string $username
-        * @return
+        * @return string
         */
        static function gender( $parser, $username ) {
                wfProfileIn( __METHOD__ );
@@ -343,7 +343,7 @@ class CoreParserFunctions {
        /**
         * @param Parser $parser
         * @param string $text
-        * @return
+        * @return string
         */
        static function plural( $parser, $text = '' ) {
                $forms = array_slice( func_get_args(), 2 );
@@ -481,6 +481,8 @@ class CoreParserFunctions {
         * corresponding magic word
         * Note: function name changed to "mwnamespace" rather than "namespace"
         * to not break PHP 5.3
+        * @param Parser $parser
+        * @param string $title
         * @return mixed|string
         */
        static function mwnamespace( $parser, $title = null ) {
@@ -536,6 +538,8 @@ class CoreParserFunctions {
        /**
         * Functions to get and normalize pagenames, corresponding to the magic words
         * of the same names
+        * @param Parser $parser
+        * @param string $title
         * @return string
         */
        static function pagename( $parser, $title = null ) {
@@ -641,6 +645,10 @@ class CoreParserFunctions {
         * Return the number of pages, files or subcats in the given category,
         * or 0 if it's nonexistent. This is an expensive parser function and
         * can't be called too many times per page.
+        * @param Parser $parser
+        * @param string $name
+        * @param string $arg1
+        * @param string $arg2
         * @return string
         */
        static function pagesincategory( $parser, $name = '', $arg1 = null, $arg2 = null ) {
@@ -1011,6 +1019,7 @@ class CoreParserFunctions {
         * Get the pageid of a specified page
         * @param Parser $parser
         * @param string $title Title to get the pageid from
+        * @return int|null|string
         * @since 1.23
         */
        public static function pageid( $parser, $title = null ) {
@@ -1055,6 +1064,7 @@ class CoreParserFunctions {
         * Get the id from the last revision of a specified page.
         * @param Parser $parser
         * @param string $title Title to get the id from
+        * @return int|null|string
         * @since 1.23
         */
        public static function revisionid( $parser, $title = null ) {
@@ -1071,6 +1081,7 @@ class CoreParserFunctions {
         * Get the day from the last revision of a specified page.
         * @param Parser $parser
         * @param string $title Title to get the day from
+        * @return string
         * @since 1.23
         */
        public static function revisionday( $parser, $title = null ) {
@@ -1087,6 +1098,7 @@ class CoreParserFunctions {
         * Get the day with leading zeros from the last revision of a specified page.
         * @param Parser $parser
         * @param string $title Title to get the day from
+        * @return string
         * @since 1.23
         */
        public static function revisionday2( $parser, $title = null ) {
@@ -1103,6 +1115,7 @@ class CoreParserFunctions {
         * Get the month with leading zeros from the last revision of a specified page.
         * @param Parser $parser
         * @param string $title Title to get the month from
+        * @return string
         * @since 1.23
         */
        public static function revisionmonth( $parser, $title = null ) {
@@ -1119,6 +1132,7 @@ class CoreParserFunctions {
         * Get the month from the last revision of a specified page.
         * @param Parser $parser
         * @param string $title Title to get the month from
+        * @return string
         * @since 1.23
         */
        public static function revisionmonth1( $parser, $title = null ) {
@@ -1135,6 +1149,7 @@ class CoreParserFunctions {
         * Get the year from the last revision of a specified page.
         * @param Parser $parser
         * @param string $title Title to get the year from
+        * @return string
         * @since 1.23
         */
        public static function revisionyear( $parser, $title = null ) {
@@ -1151,6 +1166,7 @@ class CoreParserFunctions {
         * Get the timestamp from the last revision of a specified page.
         * @param Parser $parser
         * @param string $title Title to get the timestamp from
+        * @return string
         * @since 1.23
         */
        public static function revisiontimestamp( $parser, $title = null ) {
@@ -1167,6 +1183,7 @@ class CoreParserFunctions {
         * Get the user from the last revision of a specified page.
         * @param Parser $parser
         * @param string $title Title to get the user from
+        * @return string
         * @since 1.23
         */
        public static function revisionuser( $parser, $title = null ) {

diff --git a/includes/parser/DateFormatter.php b/includes/parser/DateFormatter.php
index 54c6dec..f022646 100644 (file)
--- a/includes/parser/DateFormatter.php
+++ b/includes/parser/DateFormatter.php
@@ -324,6 +324,7 @@ class DateFormatter {
                        }
                }
                if ( $fail ) {
+                       /** @todo FIXME: $matches doesn't exist here, what's expected? */
                        $text = $matches[0];
                }
 
@@ -385,6 +386,7 @@ class DateFormatter {
 
        /**
         * @todo document
+        * @param string $iso
         * @return int|string
         */
        function makeNormalYear( $iso ) {

diff --git a/includes/parser/LinkHolderArray.php b/includes/parser/LinkHolderArray.php
index dc0f933..fd84265 100644 (file)
--- a/includes/parser/LinkHolderArray.php
+++ b/includes/parser/LinkHolderArray.php
@@ -161,6 +161,7 @@ class LinkHolderArray {
        /**
         * Get a subset of the current LinkHolderArray which is sufficient to
         * interpret the given text.
+        * @param string $text
         * @return LinkHolderArray
         */
        function getSubArray( $text ) {
@@ -263,12 +264,14 @@ class LinkHolderArray {
        /**
         * Replace <!--LINK--> link placeholders with actual links, in the buffer
         *
+        * @param $text
         * @return array Array of link CSS classes, indexed by PDBK.
         */
        function replace( &$text ) {
                wfProfileIn( __METHOD__ );
 
-               $colours = $this->replaceInternal( $text ); // FIXME: replaceInternal doesn't return a value
+               /** @todo FIXME: replaceInternal doesn't return a value */
+               $colours = $this->replaceInternal( $text );
                $this->replaceInterwiki( $text );
 
                wfProfileOut( __METHOD__ );

diff --git a/includes/parser/Parser.php b/includes/parser/Parser.php
index 5a6dd9e..11a73f3 100644 (file)
--- a/includes/parser/Parser.php
+++ b/includes/parser/Parser.php
@@ -318,8 +318,6 @@ class Parser {
        private $mRevIdForTs;
 
        /**
-        * Constructor
-        *
         * @param array $conf
         */
        public function __construct( $conf = array() ) {
@@ -704,7 +702,7 @@ class Parser {
         * If $frame is not provided, then template variables (e.g., {{{1}}}) within $text are not expanded
         *
         * @param string $text Text extension wants to have parsed
-        * @param PPFrame $frame The frame to use for expanding any template variables
+        * @param bool|PPFrame $frame The frame to use for expanding any template variables
         *
         * @return string
         */
@@ -746,7 +744,7 @@ class Parser {
         * hook.
         *
         * @param string $text Text to be expanded
-        * @param PPFrame $frame The frame to use for expanding any template variables
+        * @param bool|PPFrame $frame The frame to use for expanding any template variables
         * @return string
         * @since 1.19
         */
@@ -2472,7 +2470,7 @@ class Parser {
        }
 
        /**
-        * TODO: document
+        * @todo Document
         * @param string $char
         * @private
         *
@@ -2627,7 +2625,7 @@ class Parser {
 
                                if ( $openmatch or $closematch ) {
                                        $paragraphStack = false;
-                                       # TODO bug 5718: paragraph closed
+                                       # @todo bug 5718: paragraph closed
                                        $output .= $this->closeParagraph();
                                        if ( $preOpenMatch and !$preCloseMatch ) {
                                                $this->mInPre = true;
@@ -3380,8 +3378,8 @@ class Parser {
         *   'expansion-depth-exceeded' (corresponding messages:
         *       'expansion-depth-exceeded-warning',
         *       'expansion-depth-exceeded-category')
-        * @param int|null $current Current value
-        * @param int|null $max Maximum allowed, when an explicit limit has been
+        * @param string|int|null $current Current value
+        * @param string|int|null $max Maximum allowed, when an explicit limit has been
         *       exceeded, provide the values (optional)
         */
        function limitationWarn( $limitationType, $current = '', $max = '' ) {
@@ -3397,11 +3395,11 @@ class Parser {
         * replacing any variables or templates within the template.
         *
         * @param array $piece The parts of the template
-        *  $piece['title']: the title, i.e. the part before the |
-        *  $piece['parts']: the parameter array
-        *  $piece['lineStart']: whether the brace was at the start of a line
+        *   $piece['title']: the title, i.e. the part before the |
+        *   $piece['parts']: the parameter array
+        *   $piece['lineStart']: whether the brace was at the start of a line
         * @param PPFrame $frame The current frame, contains template arguments
-        * @throws MWException
+        * @throws Exception
         * @return string The text of the template
         * @private
         */
@@ -3743,6 +3741,7 @@ class Parser {
         * @param PPFrame $frame The current frame, contains template arguments
         * @param string $function Function name
         * @param array $args Arguments to the function
+        * @throws MWException
         * @return array
         */
        public function callParserFunction( $frame, $function, array $args = array() ) {
@@ -3920,7 +3919,7 @@ class Parser {
         * Can be overridden via ParserOptions::setTemplateCallback().
         *
         * @param Title $title
-        * @param Parser $parser
+        * @param bool|Parser $parser
         *
         * @return array
         */
@@ -5727,7 +5726,7 @@ class Parser {
 
        /**
         * @param string $caption
-        * @param LinkHolderArray $holders
+        * @param LinkHolderArray|bool $holders
         * @return mixed|string
         */
        protected function stripAltText( $caption, $holders ) {
@@ -5768,7 +5767,7 @@ class Parser {
         * values, so they can be safely tested and escaped.
         *
         * @param string $text
-        * @param PPFrame $frame
+        * @param bool|PPFrame $frame
         * @return string
         */
        function attributeStripCallback( &$text, $frame = false ) {

diff --git a/includes/parser/ParserCache.php b/includes/parser/ParserCache.php
index f5f9441..33f0f96 100644 (file)
--- a/includes/parser/ParserCache.php
+++ b/includes/parser/ParserCache.php
@@ -26,6 +26,7 @@
  * @todo document
  */
 class ParserCache {
+       /** @var MWMemcached  */
        private $mMemc;
        /**
         * Get an instance of this object

diff --git a/includes/parser/Preprocessor.php b/includes/parser/Preprocessor.php
index 768dc9a..b8e262a 100644 (file)
--- a/includes/parser/Preprocessor.php
+++ b/includes/parser/Preprocessor.php
@@ -86,8 +86,8 @@ interface PPFrame {
        /**
         * Create a child frame
         *
-        * @param array $args
-        * @param Title $title
+        * @param array|bool $args
+        * @param bool|Title $title
         * @param int $indexOffset A number subtracted from the index attributes of the arguments
         *
         * @return PPFrame

diff --git a/includes/parser/Preprocessor_DOM.php b/includes/parser/Preprocessor_DOM.php
index ca7fd60..ecdefb7 100644 (file)
--- a/includes/parser/Preprocessor_DOM.php
+++ b/includes/parser/Preprocessor_DOM.php
@@ -909,6 +909,7 @@ class PPDStackElement {
        /**
         * Get the output string that would result if the close is not found.
         *
+        * @param bool|int $openingCount
         * @return string
         */
        function breakSyntax( $openingCount = false ) {
@@ -1487,10 +1488,10 @@ class PPTemplateFrame_DOM extends PPFrame_DOM {
 
        /**
         * @param Preprocessor $preprocessor
-        * @param PPFrame_DOM $parent
+        * @param bool|PPFrame_DOM $parent
         * @param array $numberedArgs
         * @param array $namedArgs
-        * @param Title $title
+        * @param bool|Title $title
         */
        function __construct( $preprocessor, $parent = false, $numberedArgs = array(),
                $namedArgs = array(), $title = false

diff --git a/includes/parser/Preprocessor_Hash.php b/includes/parser/Preprocessor_Hash.php
index 137f885..dae6335 100644 (file)
--- a/includes/parser/Preprocessor_Hash.php
+++ b/includes/parser/Preprocessor_Hash.php
@@ -870,7 +870,7 @@ class PPDAccum_Hash {
         * Append a PPAccum_Hash
         * Takes over ownership of the nodes in the source argument. These nodes may
         * subsequently be modified, especially nextSibling.
-        * @param PPAccum_Hash $accum
+        * @param PPDAccum_Hash $accum
         */
        function addAccum( $accum ) {
                if ( $accum->lastNode === false ) {
@@ -1395,7 +1395,7 @@ class PPTemplateFrame_Hash extends PPFrame_Hash {
         * @param bool|PPFrame $parent
         * @param array $numberedArgs
         * @param array $namedArgs
-        * @param Title $title
+        * @param bool|Title $title
         */
        function __construct( $preprocessor, $parent = false, $numberedArgs = array(),
                $namedArgs = array(), $title = false