From 5b6dd9761264e76612fec63cf68907faf93098ff Mon Sep 17 00:00:00 2001 From: Daniel Cannon Date: Sat, 12 Jan 2008 07:08:17 +0000 Subject: [PATCH] API: Various docu and clean-up. --- includes/api/ApiBase.php | 52 +++++++++++++--- includes/api/ApiBlock.php | 14 ++++- includes/api/ApiChangeRights.php | 5 +- includes/api/ApiDelete.php | 97 ++++++++++++++++------------- includes/api/ApiExpandTemplates.php | 4 ++ includes/api/ApiLogout.php | 8 ++- includes/api/ApiUnblock.php | 6 ++ 7 files changed, 133 insertions(+), 53 deletions(-) diff --git a/includes/api/ApiBase.php b/includes/api/ApiBase.php index af2a3b58e7..0a10311af5 100644 --- a/includes/api/ApiBase.php +++ b/includes/api/ApiBase.php @@ -63,11 +63,35 @@ abstract class ApiBase { $this->mModulePrefix = $modulePrefix; } - /** - * Executes this module + /***************************************************************************** + * ABSTRACT METHODS * + *****************************************************************************/ + + /** + * Evaluates the parameters, performs the requested query, and sets up the + * result. Concrete implementations of ApiBase must override this method to + * provide whatever functionality their module offers. Implementations must + * not produce any output on their own and are not expected to handle any + * errors. + * + * The execute method will be invoked directly by ApiMain immediately before + * the result of the module is output. Aside from the constructor, implementations + * should assume that no other methods will be called externally on the module + * before the result is processed. + * + * The result data should be stored in the result object referred to by + * "getResult()". Refer to ApiResult.php for details on populating a result + * object. */ public abstract function execute(); + /** + * Returns a String that identifies the version of the extending class. Typically + * includes the class name, the svn revision, timestamp, and last author. May + * be severely incorrect in many implementations! + */ + public abstract function getVersion(); + /** * Get the name of the module being executed by this instance */ @@ -100,14 +124,16 @@ abstract class ApiBase { } /** - * If this module's $this is the same as $this->mMainModule, its the root, otherwise no + * Returns true if this module is the main module ($this === $this->mMainModule), + * false otherwise. */ public function isMain() { return $this === $this->mMainModule; } /** - * Get result object + * Get the result object. Please refer to the documentation in ApiResult.php + * for details on populating and accessing data in a result object. */ public function getResult() { // Main module has getResult() method overriden @@ -125,7 +151,8 @@ abstract class ApiBase { } /** - * Set warning section for this module. Users should monitor this section to notice any changes in API. + * Set warning section for this module. Users should monitor this section to + * notice any changes in API. */ public function setWarning($warning) { $msg = array(); @@ -196,6 +223,10 @@ abstract class ApiBase { return $msg; } + /** + * Generates the parameter descriptions for this module, to be displayed in the + * module's help. + */ public function makeHelpMsgParameters() { $params = $this->getAllowedParams(); if ($params !== false) { @@ -208,7 +239,7 @@ abstract class ApiBase { if (is_array($desc)) $desc = implode($paramPrefix, $desc); - @ $type = $paramSettings[self :: PARAM_TYPE]; + $type = $paramSettings[self :: PARAM_TYPE]; if (isset ($type)) { if (isset ($paramSettings[self :: PARAM_ISMULTI])) $prompt = 'Values (separate with \'|\'): '; @@ -325,6 +356,10 @@ abstract class ApiBase { return $this->getParameterFromSettings($paramName, $paramSettings); } + /** + * Returns an array of the namespaces (by integer id) that exist on the + * wiki. Used primarily in help documentation. + */ public static function getValidNamespaces() { static $mValidNamespaces = null; if (is_null($mValidNamespaces)) { @@ -341,6 +376,7 @@ abstract class ApiBase { /** * Using the settings determine the value for the given parameter + * * @param $paramName String: parameter name * @param $paramSettings Mixed: default value or an array of settings using PARAM_* constants. * @param $parseMaxLimit Boolean: parse limit when max is given? @@ -637,8 +673,10 @@ abstract class ApiBase { print "\n\n"; } - public abstract function getVersion(); + /** + * Returns a String that identifies the version of this class. + */ public static function getBaseVersion() { return __CLASS__ . ': $Id$'; } diff --git a/includes/api/ApiBlock.php b/includes/api/ApiBlock.php index ef9ad6cc22..a91657e97e 100644 --- a/includes/api/ApiBlock.php +++ b/includes/api/ApiBlock.php @@ -28,14 +28,26 @@ if (!defined('MEDIAWIKI')) { } /** +* API module that facilitates the blocking of users. Requires API write mode +* to be enabled. +* * @addtogroup API */ class ApiBlock extends ApiBase { + /** + * Std ctor. + */ public function __construct($main, $action) { parent :: __construct($main, $action); } + /** + * Blocks the user specified in the parameters for the given expiry, with the + * given reason, and with all other settings provided in the params. If the block + * succeeds, produces a result containing the details of the block and notice + * of success. If it fails, the result will specify the nature of the error. + */ public function execute() { global $wgUser; $this->getMain()->requestWriteMode(); @@ -141,7 +153,7 @@ class ApiBlock extends ApiBase { 'nocreate' => 'Prevent account creation', 'autoblock' => 'Automatically block the last used IP address, and any subsequent IP addresses they try to login from', 'noemail' => 'Prevent user from sending e-mail through the wiki', - 'hidename' => 'Hide the username from the block log.' + 'hidename' => 'Hide the username from the block log. (Requires the "hideuser" right.)' ); } diff --git a/includes/api/ApiChangeRights.php b/includes/api/ApiChangeRights.php index 395f1c9f48..f51bc04b38 100644 --- a/includes/api/ApiChangeRights.php +++ b/includes/api/ApiChangeRights.php @@ -27,7 +27,10 @@ if (!defined('MEDIAWIKI')) { require_once ("ApiBase.php"); } -/** +/** + * API module that facilitates the changing of user rights. The API eqivalent of + * Special:Userrights. Requires API write mode to be enabled. + * * @addtogroup API */ class ApiChangeRights extends ApiBase { diff --git a/includes/api/ApiDelete.php b/includes/api/ApiDelete.php index 6ca9f953ea..22360fb6da 100644 --- a/includes/api/ApiDelete.php +++ b/includes/api/ApiDelete.php @@ -29,6 +29,9 @@ if (!defined('MEDIAWIKI')) { /** + * API module that facilitates deleting pages. The API eqivalent of action=delete. + * Requires API write mode to be enabled. + * * @addtogroup API */ class ApiDelete extends ApiBase { @@ -37,51 +40,21 @@ class ApiDelete extends ApiBase { parent :: __construct($main, $action); } + /* Return values for the delete function. */ + const DELETE_SUCCESS = 0; + const DELETE_PERM = 1; + const DELETE_BLOCKED = 2; + const DELETE_READONLY = 3; + const DELETE_BADTOKEN = 4; + const DELETE_BADARTICLE = 5; + /** - * We have our own delete() function, since Article.php's implementation is split in two phases - * @param Article $article - Article object to work on - * @param string $token - Delete token (same as edit token) - * @param string $reason - Reason for the deletion. Autogenerated if NULL - * @return DELETE_SUCCESS on success, DELETE_* on failure + * Extracts the title, token, and reason from the request parameters and invokes + * the local delete() function with these as arguments. It does not make use of + * the delete function specified by Article.php. If the deletion succeeds, the + * details of the article deleted and the reason for deletion are added to the + * result object. */ - - const DELETE_SUCCESS = 0; - const DELETE_PERM = 1; - const DELETE_BLOCKED = 2; - const DELETE_READONLY = 3; - const DELETE_BADTOKEN = 4; - const DELETE_BADARTICLE = 5; - - public static function delete(&$article, $token, &$reason = NULL) - { - global $wgUser; - - // Check permissions first - if(!$article->mTitle->userCan('delete')) - return self::DELETE_PERM; - if($wgUser->isBlocked()) - return self::DELETE_BLOCKED; - if(wfReadOnly()) - return self::DELETE_READONLY; - - // Check token - if(!$wgUser->matchEditToken($token)) - return self::DELETE_BADTOKEN; - - // Auto-generate a summary, if necessary - if(is_null($reason)) - { - $reason = $article->generateReason($hasHistory); - if($reason === false) - return self::DELETE_BADARTICLE; - } - - // Luckily, Article.php provides a reusable delete function that does the hard work for us - if($article->doDeleteArticle($reason)) - return self::DELETE_SUCCESS; - return self::DELETE_BADARTICLE; - } - public function execute() { global $wgUser; $this->getMain()->requestWriteMode(); @@ -136,6 +109,44 @@ class ApiDelete extends ApiBase { $r = array('title' => $titleObj->getPrefixedText(), 'reason' => $reason); $this->getResult()->addValue(null, $this->getModuleName(), $r); } + + /** + * We have our own delete() function, since Article.php's implementation is split in two phases + * + * @param Article $article - Article object to work on + * @param string $token - Delete token (same as edit token) + * @param string $reason - Reason for the deletion. Autogenerated if NULL + * @return DELETE_SUCCESS on success, DELETE_* on failure + */ + public static function delete(&$article, $token, &$reason = NULL) + { + global $wgUser; + + // Check permissions first + if(!$article->mTitle->userCan('delete')) + return self::DELETE_PERM; + if($wgUser->isBlocked()) + return self::DELETE_BLOCKED; + if(wfReadOnly()) + return self::DELETE_READONLY; + + // Check token + if(!$wgUser->matchEditToken($token)) + return self::DELETE_BADTOKEN; + + // Auto-generate a summary, if necessary + if(is_null($reason)) + { + $reason = $article->generateReason($hasHistory); + if($reason === false) + return self::DELETE_BADARTICLE; + } + + // Luckily, Article.php provides a reusable delete function that does the hard work for us + if($article->doDeleteArticle($reason)) + return self::DELETE_SUCCESS; + return self::DELETE_BADARTICLE; + } protected function getAllowedParams() { return array ( diff --git a/includes/api/ApiExpandTemplates.php b/includes/api/ApiExpandTemplates.php index df99ba1099..9d8a7af40e 100644 --- a/includes/api/ApiExpandTemplates.php +++ b/includes/api/ApiExpandTemplates.php @@ -29,6 +29,10 @@ if (!defined('MEDIAWIKI')) { } /** + * API module that functions as a shortcut to the wikitext preprocessor. Expands + * any templates in a provided string, and returns the result of this expansion + * to the caller. + * * @addtogroup API */ class ApiExpandTemplates extends ApiBase { diff --git a/includes/api/ApiLogout.php b/includes/api/ApiLogout.php index 34dbb83e58..0d74d6b4f9 100644 --- a/includes/api/ApiLogout.php +++ b/includes/api/ApiLogout.php @@ -28,6 +28,12 @@ if (!defined('MEDIAWIKI')) { require_once ('ApiBase.php'); } +/** + * API module to allow users to log out of the wiki. API equivalent of + * Special:Userlogout. + * + * @addtogroup API + */ class ApiLogout extends ApiBase { public function __construct($main, $action) { @@ -62,4 +68,4 @@ class ApiLogout extends ApiBase { public function getVersion() { return __CLASS__ . ': $Id$'; } -} \ No newline at end of file +} diff --git a/includes/api/ApiUnblock.php b/includes/api/ApiUnblock.php index 71a8706c54..a09c19ae0c 100644 --- a/includes/api/ApiUnblock.php +++ b/includes/api/ApiUnblock.php @@ -28,6 +28,9 @@ if (!defined('MEDIAWIKI')) { } /** + * API module that facilitates the unblocking of users. Requires API write mode + * to be enabled. + * * @addtogroup API */ class ApiUnblock extends ApiBase { @@ -36,6 +39,9 @@ class ApiUnblock extends ApiBase { parent :: __construct($main, $action); } + /** + * Unblocks the specified user or provides the reason the unblock failed. + */ public function execute() { global $wgUser; $this->getMain()->requestWriteMode(); -- 2.20.1