From 1aead61d4c1d17beca71b36678fd007877f8cb88 Mon Sep 17 00:00:00 2001 From: mrbluesky Date: Sun, 15 Apr 2012 02:12:01 +0200 Subject: [PATCH] Add and fix comments in some includes files Change-Id: If781ad1a9eeba8310cef97dc9786685e8b265fa1 --- includes/Action.php | 28 ++++++++++++----- includes/AjaxDispatcher.php | 21 ++++++++++--- includes/AjaxResponse.php | 61 +++++++++++++++++++++++++++++++------ includes/Article.php | 46 ++++++++++++++++++++++------ includes/AuthPlugin.php | 2 ++ includes/AutoLoader.php | 1 + 6 files changed, 127 insertions(+), 32 deletions(-) diff --git a/includes/Action.php b/includes/Action.php index a8c0436887..a9891ec772 100644 --- a/includes/Action.php +++ b/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; } diff --git a/includes/AjaxDispatcher.php b/includes/AjaxDispatcher.php index cafe4db5d1..e3df520766 100644 --- a/includes/AjaxDispatcher.php +++ b/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. diff --git a/includes/AjaxResponse.php b/includes/AjaxResponse.php index 52f3e2b9b4..6bf94ccb75 100644 --- a/includes/AjaxResponse.php +++ b/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 */ diff --git a/includes/Article.php b/includes/Article.php index a8df6c9b1b..ded8c497f2 100644 --- a/includes/Article.php +++ b/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' => , 'follow' => + * @return Array: 'index' => \, 'follow' => \ */ 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(); diff --git a/includes/AuthPlugin.php b/includes/AuthPlugin.php index 07a614aeff..e550473713 100644 --- a/includes/AuthPlugin.php +++ b/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; diff --git a/includes/AutoLoader.php b/includes/AutoLoader.php index 0e891d776a..11f44a83e8 100644 --- a/includes/AutoLoader.php +++ b/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 ) { -- 2.20.1