From: Siebrand Mazeland <siebrand@kitano.nl>
Date: Sat, 10 May 2014 23:05:51 +0000 (+0200)
Subject: Various documentation updates for includes/parser/
X-Git-Tag: 1.31.0-rc.0~15761^2
X-Git-Url: http://git.cyclocoop.org/data/%24self?a=commitdiff_plain;h=dfc7416fbe01b654b7062dcfebf4943a6ba33907;p=lhc%2Fweb%2Fwiklou.git

Various documentation updates for includes/parser/

Change-Id: I16dd3a792cc83f8c80b3652d42c055730f6d177a
---

diff --git a/includes/parser/CoreParserFunctions.php b/includes/parser/CoreParserFunctions.php
index 8d52a5bcb2..3425b6bb7c 100644
--- 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 54c6dece68..f022646765 100644
--- 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 dc0f93359a..fd84265f3c 100644
--- 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 5a6dd9e677..11a73f352a 100644
--- 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 f5f9441e37..33f0f96836 100644
--- 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 768dc9a677..b8e262ab94 100644
--- 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 ca7fd6006a..ecdefb7bdb 100644
--- 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 137f885617..dae633587d 100644
--- 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