More documentation tweaks/additions

7 files changed, 100 insertions, 5 deletions

diff --git a/includes/EditPage.php b/includes/EditPage.php
index 36e28d01b9e7..090029ff6c77 100644
--- a/includes/EditPage.php
+++ b/includes/EditPage.php
@@ -74,7 +74,12 @@ class EditPage {
 	var $autoSumm = '';
 	var $hookError = '';
 	#var $mPreviewTemplates;
+
+	/**
+	 * @var ParserOutput
+	 */
 	var $mParserOutput;
+
 	var $mBaseRevision = false;
 	var $mShowSummaryField = true;
 
@@ -2046,10 +2051,15 @@ HTML
 		return $previewhead . $previewHTML . $this->previewTextAfterContent;
 	}
 
+	/**
+	 * @return Array
+	 */
 	function getTemplates() {
 		if ( $this->preview || $this->section != '' ) {
 			$templates = array();
-			if ( !isset( $this->mParserOutput ) ) return $templates;
+			if ( !isset( $this->mParserOutput ) ) {
+				return $templates;
+			}
 			foreach( $this->mParserOutput->getTemplates() as $ns => $template) {
 				foreach( array_keys( $template ) as $dbk ) {
 					$templates[] = Title::makeTitle($ns, $dbk);
@@ -2617,6 +2627,11 @@ HTML
 			: $text;
 	}
 
+	/**
+	 * @param $request WebRequest
+	 * @param $text string
+	 * @return string
+	 */
 	function safeUnicodeText( $request, $text ) {
 		$text = rtrim( $text );
 		return $request->getBool( 'safemode' )
diff --git a/includes/ExternalUser.php b/includes/ExternalUser.php
index 88dfc6eb7602..37716390a57a 100644
--- a/includes/ExternalUser.php
+++ b/includes/ExternalUser.php
@@ -98,7 +98,7 @@ abstract class ExternalUser {
 	 * This is a wrapper around newFromId().
 	 *
 	 * @param $user User
-	 * @return mixed ExternalUser or false
+	 * @return ExternalUser|false
 	 */
 	public static function newFromUser( $user ) {
 		global $wgExternalAuthType;
diff --git a/includes/MagicWord.php b/includes/MagicWord.php
index 663d7a7e2463..99bd0865e0a2 100644
--- a/includes/MagicWord.php
+++ b/includes/MagicWord.php
@@ -251,7 +251,7 @@ class MagicWord {
 	/**
 	 * Get a MagicWordArray of double-underscore entities
 	 *
-	 * @return array
+	 * @return MagicWordArray
 	 */
 	static function getDoubleUnderscoreArray() {
 		if ( is_null( self::$mDoubleUnderscoreArray ) ) {
diff --git a/includes/SkinTemplate.php b/includes/SkinTemplate.php
index f639cb09942a..ac112b6097e8 100644
--- a/includes/SkinTemplate.php
+++ b/includes/SkinTemplate.php
@@ -1420,6 +1420,8 @@ abstract class QuickTemplate {
 
 	/**
 	 * @private
+	 *
+	 * @return bool
 	 */
 	function haveMsg( $str ) {
 		$msg = $this->translator->translate( $str );
diff --git a/includes/parser/Parser.php b/includes/parser/Parser.php
index bdb47b12295d..6224ae4e8e93 100644
--- a/includes/parser/Parser.php
+++ b/includes/parser/Parser.php
@@ -109,7 +109,14 @@ class Parser {
 	var $mImageParamsMagicArray = array();
 	var $mMarkerIndex = 0;
 	var $mFirstCall = true;
-	var $mVariables, $mSubstWords; # Initialised by initialiseVariables()
+
+	# Initialised by initialiseVariables()
+	var $mVariables;
+
+	/**
+	 * @var MagicWordArray
+	 */
+	var $mSubstWords;
 	var $mConf, $mPreprocessor, $mExtLinkBracketedRegex, $mUrlProtocols; # Initialised in constructor
 
 	# Cleared with clearState():
@@ -125,7 +132,12 @@ class Parser {
 	var $mStripState;
 
 	var $mIncludeCount, $mArgStack, $mLastSection, $mInPre;
-	var $mLinkHolders, $mLinkID;
+	/**
+	 * @var LinkHolderArray
+	 */
+	var $mLinkHolders;
+
+	var $mLinkID;
 	var $mIncludeSizes, $mPPNodeCount, $mDefaultSort;
 	var $mTplExpandCache; # empty-frame expansion cache
 	var $mTplRedirCache, $mTplDomCache, $mHeadings, $mDoubleUnderscores;
@@ -3518,6 +3530,9 @@ class Parser {
 	/**
 	 * Transclude an interwiki link.
 	 *
+	 * @param $title Title
+	 * @param $action
+	 *
 	 * @return string
 	 */
 	function interwikiTransclude( $title, $action ) {
@@ -5010,6 +5025,11 @@ class Parser {
 		return $ret;
 	}
 
+	/**
+	 * @param $caption
+	 * @param $holders LinkHolderArray
+	 * @return mixed|String
+	 */
 	protected function stripAltText( $caption, $holders ) {
 		# Strip bad stuff out of the title (tooltip).  We can't just use
 		# replaceLinkHoldersText() here, because if this function is called
diff --git a/includes/parser/Preprocessor_DOM.php b/includes/parser/Preprocessor_DOM.php
index 7ecbe1941cad..157e97315d84 100644
--- a/includes/parser/Preprocessor_DOM.php
+++ b/includes/parser/Preprocessor_DOM.php
@@ -1157,6 +1157,8 @@ class PPFrame_DOM implements PPFrame {
 	/**
 	 * Makes an object that, when expand()ed, will be the same as one obtained
 	 * with implode()
+	 *
+	 * @return array
 	 */
 	function virtualImplode( $sep /*, ... */ ) {
 		$args = array_slice( func_get_args(), 1 );
@@ -1424,6 +1426,9 @@ class PPNode_DOM implements PPNode {
 		$this->node = $node;
 	}
 
+	/**
+	 * @return DOMXPath
+	 */
 	function getXPath() {
 		if ( $this->xpath === null ) {
 			$this->xpath = new DOMXPath( $this->node->ownerDocument );
@@ -1443,22 +1448,39 @@ class PPNode_DOM implements PPNode {
 		return $s;
 	}
 
+	/**
+	 * @return bool|PPNode_DOM
+	 */
 	function getChildren() {
 		return $this->node->childNodes ? new self( $this->node->childNodes ) : false;
 	}
 
+	/**
+	 * @return bool|PPNode_DOM
+	 */
 	function getFirstChild() {
 		return $this->node->firstChild ? new self( $this->node->firstChild ) : false;
 	}
 
+	/**
+	 * @return bool|PPNode_DOM
+	 */
 	function getNextSibling() {
 		return $this->node->nextSibling ? new self( $this->node->nextSibling ) : false;
 	}
 
+	/**
+	 * @param $type
+	 *
+	 * @return bool|PPNode_DOM
+	 */
 	function getChildrenOfType( $type ) {
 		return new self( $this->getXPath()->query( $type, $this->node ) );
 	}
 
+	/**
+	 * @return int
+	 */
 	function getLength() {
 		if ( $this->node instanceof DOMNodeList ) {
 			return $this->node->length;
@@ -1467,11 +1489,18 @@ class PPNode_DOM implements PPNode {
 		}
 	}
 
+	/**
+	 * @param $i
+	 * @return bool|PPNode_DOM
+	 */
 	function item( $i ) {
 		$item = $this->node->item( $i );
 		return $item ? new self( $item ) : false;
 	}
 
+	/**
+	 * @return string
+	 */
 	function getName() {
 		if ( $this->node instanceof DOMNodeList ) {
 			return '#nodelist';
@@ -1485,6 +1514,8 @@ class PPNode_DOM implements PPNode {
 	 *    name          PPNode name
 	 *    index         String index
 	 *    value         PPNode value
+	 *
+	 * @return array
 	 */
 	function splitArg() {
 		$xpath = $this->getXPath();
@@ -1504,6 +1535,8 @@ class PPNode_DOM implements PPNode {
 	/**
 	 * Split an <ext> node into an associative array containing name, attr, inner and close
 	 * All values in the resulting array are PPNodes. Inner and close are optional.
+	 *
+	 * @return array
 	 */
 	function splitExt() {
 		$xpath = $this->getXPath();
diff --git a/includes/parser/Preprocessor_Hash.php b/includes/parser/Preprocessor_Hash.php
index 1cf136bd8cb5..b84b39deb7f5 100644
--- a/includes/parser/Preprocessor_Hash.php
+++ b/includes/parser/Preprocessor_Hash.php
@@ -24,10 +24,17 @@ class Preprocessor_Hash implements Preprocessor {
 		$this->parser = $parser;
 	}
 
+	/**
+	 * @return PPFrame_Hash
+	 */
 	function newFrame() {
 		return new PPFrame_Hash( $this );
 	}
 
+	/**
+	 * @param $args
+	 * @return PPCustomFrame_Hash
+	 */
 	function newCustomFrame( $args ) {
 		return new PPCustomFrame_Hash( $this, $args );
 	}
@@ -1231,6 +1238,13 @@ class PPTemplateFrame_Hash extends PPFrame_Hash {
 	var $numberedArgs, $namedArgs, $parent;
 	var $numberedExpansionCache, $namedExpansionCache;
 
+	/**
+	 * @param $preprocessor
+	 * @param $parent
+	 * @param $numberedArgs array
+	 * @param $namedArgs array
+	 * @param $title Title
+	 */
 	function __construct( $preprocessor, $parent = false, $numberedArgs = array(), $namedArgs = array(), $title = false ) {
 		parent::__construct( $preprocessor );
 
@@ -1267,11 +1281,16 @@ class PPTemplateFrame_Hash extends PPFrame_Hash {
 	}
 	/**
 	 * Returns true if there are no arguments in this frame
+	 *
+	 * @return bool
 	 */
 	function isEmpty() {
 		return !count( $this->numberedArgs ) && !count( $this->namedArgs );
 	}
 
+	/**
+	 * @return array
+	 */
 	function getArguments() {
 		$arguments = array();
 		foreach ( array_merge(
@@ -1282,6 +1301,9 @@ class PPTemplateFrame_Hash extends PPFrame_Hash {
 		return $arguments;
 	}
 
+	/**
+	 * @return array
+	 */
 	function getNumberedArguments() {
 		$arguments = array();
 		foreach ( array_keys($this->numberedArgs) as $key ) {
@@ -1290,6 +1312,9 @@ class PPTemplateFrame_Hash extends PPFrame_Hash {
 		return $arguments;
 	}
 
+	/**
+	 * @return array
+	 */
 	function getNamedArguments() {
 		$arguments = array();
 		foreach ( array_keys($this->namedArgs) as $key ) {