API: Various docu and clean-up.

[lhc/web/wiklou.git] / includes / api / ApiDelete.php

diff --git a/includes/api/ApiDelete.php b/includes/api/ApiDelete.php
index 6ca9f95..22360fb 100644 (file)
--- 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 (