Add and fix comments in some includes files

Change-Id: If781ad1a9eeba8310cef97dc9786685e8b265fa1

includes/Action.php

@@ -29,24 +29,28 @@
  *
  * To add an action in an extension, create a subclass of Action, and add the key to
  * $wgActions.  There is also the deprecated UnknownAction hook
+ *
+ * Actions generally fall into two groups: the show-a-form-then-do-something-with-the-input
+ * format (protect, delete, move, etc), and the just-do-something format (watch, rollback,
+ * patrol, etc). The FormAction and FormlessAction classes respresent these two groups.
  */
 abstract class Action {
 
 	/**
 	 * Page on which we're performing the action
-	 * @var Page
+	 * @var Page $page
 	 */
 	protected $page;
 
 	/**
 	 * IContextSource if specified; otherwise we'll use the Context from the Page
-	 * @var IContextSource
+	 * @var IContextSource $context
 	 */
 	protected $context;
 
 	/**
 	 * The fields used to create the HTMLForm
-	 * @var Array
+	 * @var Array $fields
 	 */
 	protected $fields;
 
@@ -355,6 +359,9 @@ abstract class Action {
 	public abstract function execute();
 }
 
+/**
+ * An action which shows a form and does something based on the input from the form
+ */
 abstract class FormAction extends Action {
 
 	/**
@@ -449,8 +456,8 @@ abstract class FormAction extends Action {
 	/**
 	 * @see Action::execute()
 	 * @throws ErrorPageError
-	 * @param array|null $data
-	 * @param bool $captureErrors
+	 * @param $data array|null
+	 * @param $captureErrors bool
 	 * @return bool
 	 */
 	public function execute( array $data = null, $captureErrors = true ) {
@@ -491,9 +498,7 @@ abstract class FormAction extends Action {
 }
 
 /**
- * Actions generally fall into two groups: the show-a-form-then-do-something-with-the-input
- * format (protect, delete, move, etc), and the just-do-something format (watch, rollback,
- * patrol, etc).
+ * An action which just does something, without showing a form first.
  */
 abstract class FormlessAction extends Action {
 
@@ -512,10 +517,17 @@ abstract class FormlessAction extends Action {
 		return false;
 	}
 
+	/**
+	 * @param $data Array
+	 * @return bool
+	 */
 	public function onSubmit( $data ) {
 		return false;
 	}
 
+	/**
+	 * @return bool
+	 */
 	public function onSuccess() {
 		return false;
 	}

includes/AjaxDispatcher.php

@@ -30,16 +30,26 @@
  * @ingroup Ajax
  */
 class AjaxDispatcher {
-	/** The way the request was made, either a 'get' or a 'post' */
+	/**
+	 * The way the request was made, either a 'get' or a 'post'
+	 * @var string $mode
+	 */
 	private $mode;
 
-	/** Name of the requested handler */
+	/**
+	 * Name of the requested handler
+	 * @var string $func_name
+	 */
 	private $func_name;
 
-	/** Arguments passed */
+	/** Arguments passed
+	 * @var array $args
+	 */
 	private $args;
 
-	/** Load up our object with user supplied data */
+	/**
+	 * Load up our object with user supplied data
+	 */
 	function __construct() {
 		wfProfileIn( __METHOD__ );
 
@@ -80,7 +90,8 @@ class AjaxDispatcher {
 		wfProfileOut( __METHOD__ );
 	}
 
-	/** Pass the request to our internal function.
+	/**
+	 * Pass the request to our internal function.
 	 * BEWARE! Data are passed as they have been supplied by the user,
 	 * they should be carefully handled in the function processing the
 	 * request.

includes/AjaxResponse.php

@@ -28,25 +28,47 @@
  * @ingroup Ajax
  */
 class AjaxResponse {
-	/** Number of seconds to get the response cached by a proxy */
+
+	/**
+	 * Number of seconds to get the response cached by a proxy
+	 * @var int $mCacheDuration
+	 */
 	private $mCacheDuration;
 
-	/** HTTP header Content-Type */
+	/**
+	 * HTTP header Content-Type
+	 * @var string $mContentType
+	 */
 	private $mContentType;
 
-	/** Disables output. Can be set by calling $AjaxResponse->disable() */
+	/**
+	 * Disables output. Can be set by calling $AjaxResponse->disable()
+	 * @var bool $mDisabled
+	 */
 	private $mDisabled;
 
-	/** Date for the HTTP header Last-modified */
+	/**
+	 * Date for the HTTP header Last-modified
+	 * @var string|false $mLastModified
+	 */
 	private $mLastModified;
 
-	/** HTTP response code */
+	/**
+	 * HTTP response code
+	 * @var string $mResponseCode
+	 */
 	private $mResponseCode;
 
-	/** HTTP Vary header */
+	/**
+	 * HTTP Vary header
+	 * @var string $mVary
+	 */
 	private $mVary;
 
-	/** Content of our HTTP response */
+	/**
+	 * Content of our HTTP response
+	 * @var string $mText
+	 */
 	private $mText;
 
 	/**
@@ -67,22 +89,41 @@ class AjaxResponse {
 		}
 	}
 
+	/**
+	 * Set the number of seconds to get the response cached by a proxy
+	 * @param $duration int
+	 */
 	function setCacheDuration( $duration ) {
 		$this->mCacheDuration = $duration;
 	}
 
+	/**
+	 * Set the HTTP Vary header
+	 * @param $vary string
+	 */
 	function setVary( $vary ) {
 		$this->mVary = $vary;
 	}
 
+	/**
+	 * Set the HTTP response code
+	 * @param $code string
+	 */
 	function setResponseCode( $code ) {
 		$this->mResponseCode = $code;
 	}
 
+	/**
+	 * Set the HTTP header Content-Type
+	 * @param $type string
+	 */
 	function setContentType( $type ) {
 		$this->mContentType = $type;
 	}
 
+	/**
+	 * Disable output.
+	 */
 	function disable() {
 		$this->mDisabled = true;
 	}
@@ -222,8 +263,8 @@ class AjaxResponse {
 	}
 
 	/**
-	 * @param $mckey
-	 * @param $touched
+	 * @param $mckey string
+	 * @param $touched int
 	 * @return bool
 	 */
 	function loadFromMemcached( $mckey, $touched ) {
@@ -250,7 +291,7 @@ class AjaxResponse {
 	}
 
 	/**
-	 * @param $mckey
+	 * @param $mckey string
 	 * @param $expiry int
 	 * @return bool
 	 */

includes/Article.php

@@ -25,7 +25,7 @@
  *
  * This maintains WikiPage functions for backwards compatibility.
  *
- * @TODO: move and rewrite code to an Action class
+ * @todo move and rewrite code to an Action class
  *
  * See design.txt for an overview.
  * Note: edit user interface and cache support functions have been
@@ -39,42 +39,69 @@ class Article extends Page {
 	 */
 
 	/**
-	 * @var IContextSource
+	 * The context this Article is executed in
+	 * @var IContextSource $mContext
 	 */
 	protected $mContext;
 
 	/**
-	 * @var WikiPage
+	 * The WikiPage object of this instance
+	 * @var WikiPage $mPage
 	 */
 	protected $mPage;
 
 	/**
-	 * @var ParserOptions: ParserOptions object for $wgUser articles
+	 * ParserOptions object for $wgUser articles
+	 * @var ParserOptions $mParserOptions
 	 */
 	public $mParserOptions;
 
+	/**
+	 * Content of the revision we are working on
+	 * @var string $mContent
+	 */
 	var $mContent;                    // !<
+
+	/**
+	 * Is the content ($mContent) already loaded?
+	 * @var bool $mContentLoaded
+	 */
 	var $mContentLoaded = false;      // !<
+
+	/**
+	 * The oldid of the article that is to be shown, 0 for the
+	 * current revision
+	 * @var int|null $mOldId
+	 */
 	var $mOldId;                      // !<
 
 	/**
-	 * @var Title
+	 * Title from which we were redirected here
+	 * @var Title $mRedirectedFrom
 	 */
 	var $mRedirectedFrom = null;
 
 	/**
-	 * @var mixed: boolean false or URL string
+	 * URL to redirect to or false if none
+	 * @var string|false $mRedirectUrl
 	 */
 	var $mRedirectUrl = false;        // !<
+
+	/**
+	 * Revision ID of revision we are working on
+	 * @var int $mRevIdFetched
+	 */
 	var $mRevIdFetched = 0;           // !<
 
 	/**
-	 * @var Revision
+	 * Revision we are working on
+	 * @var Revision $mRevision
 	 */
 	var $mRevision = null;
 
 	/**
-	 * @var ParserOutput
+	 * ParserOutput object
+	 * @var ParserOutput $mParserOutput
 	 */
 	var $mParserOutput;
 
@@ -809,7 +836,7 @@ class Article extends Page {
 	 * merging of several policies using array_merge().
 	 * @param $policy Mixed, returns empty array on null/false/'', transparent
 	 *            to already-converted arrays, converts String.
-	 * @return Array: 'index' => <indexpolicy>, 'follow' => <followpolicy>
+	 * @return Array: 'index' => \<indexpolicy\>, 'follow' => \<followpolicy\>
 	 */
 	public static function formatRobotPolicy( $policy ) {
 		if ( is_array( $policy ) ) {
@@ -1656,6 +1683,7 @@ class Article extends Page {
 	/**
 	 * Handle action=purge
 	 * @deprecated since 1.19
+	 * @return Action|bool|null false if the action is disabled, null if it is not recognised
 	 */
 	public function purge() {
 		return Action::factory( 'purge', $this )->show();

includes/AuthPlugin.php

@@ -248,6 +248,8 @@ class AuthPlugin {
 	/**
 	 * If you want to munge the case of an account name before the final
 	 * check, now is your chance.
+	 * @param $username string
+	 * @return string
 	 */
 	public function getCanonicalName( $username ) {
 		return $username;

includes/AutoLoader.php

@@ -1066,6 +1066,7 @@ class AutoLoader {
 	 * Sanitizer that have define()s outside of their class definition. Of course
 	 * this wouldn't be necessary if everything in MediaWiki was class-based. Sigh.
 	 *
+	 * @param $class string
 	 * @return Boolean Return the results of class_exists() so we know if we were successful
 	 */
 	static function loadClass( $class ) {