* (bug 28817) Add reference help page link to API Modules

Start of this bug, fleshed out base code implemented, plus a few key modules (will finish rest up soon)

Tweaked/improved/updated some documentation as I went through also

diff --git a/includes/api/ApiBase.php b/includes/api/ApiBase.php
index 8fbeb12..360efda 100644 (file)
--- a/includes/api/ApiBase.php
+++ b/includes/api/ApiBase.php
@@ -257,8 +257,7 @@ abstract class ApiBase {
                                $msg .= "\nThis module only accepts POST requests";
                        }
                        if ( $this->isReadMode() || $this->isWriteMode() ||
-                                       $this->mustBePosted() )
-                       {
+                                       $this->mustBePosted() ) {
                                $msg .= "\n";
                        }
 
@@ -268,20 +267,8 @@ abstract class ApiBase {
                                $msg .= "Parameters:\n$paramsMsg";
                        }
 
-                       // Examples
-                       $examples = $this->getExamples();
-                       if ( $examples !== false ) {
-                               if ( !is_array( $examples ) ) {
-                                       $examples = array(
-                                               $examples
-                                       );
-                               }
-
-                               if ( count( $examples ) > 0 ) {
-                                       $msg .= 'Example' . ( count( $examples ) > 1 ? 's' : '' ) . ":\n  ";
-                                       $msg .= implode( $lnPrfx, $examples ) . "\n";
-                               }
-                       }
+                       $msg .= $this->makeHelpArrayToString( $lnPrfx, "Example", $this->getExamples() );
+                       $msg .= $this->makeHelpArrayToString( $lnPrfx, "Help page", $this->getHelpUrl() );
 
                        if ( $this->getMain()->getShowVersions() ) {
                                $versions = $this->getVersion();
@@ -304,6 +291,30 @@ abstract class ApiBase {
                return $msg;
        }
 
+       /**
+        * @param $prefix string Text to split output items
+        * @param $title string What is being output
+        * @param $input string|array
+        * @return string
+        */
+       protected function makeHelpArrayToString( $prefix, $title, $input ) {
+               if ( $input !== false ) {
+                       return '';
+               }
+               if ( !is_array( $input ) ) {
+                       $input = array(
+                               $input
+                       );
+               }
+
+               if ( count( $input ) > 0 ) {
+                       $msg = $title . ( count( $input ) > 1 ? 's' : '' ) . ":\n  ";
+                       $msg .= implode( $prefix, $input ) . "\n";
+                       return $msg;
+               }
+               return '';
+       }
+
        /**
         * Generates the parameter descriptions for this module, to be displayed in the
         * module's help.
@@ -468,8 +479,8 @@ abstract class ApiBase {
        }
 
        /**
-        * Returns usage examples for this module. Return null if no examples are available.
-        * @return mixed string or array of strings
+        * Returns usage examples for this module. Return false if no examples are available.
+        * @return false|string|array
         */
        protected function getExamples() {
                return false;
@@ -1297,6 +1308,13 @@ abstract class ApiBase {
                return $user;
        }
 
+       /**
+        * @return false|string|array Returns a false if the module has no help url, else returns a (array of) string
+        */
+       public function getHelpUrl() {
+               return false;
+       }
+
        /**
         * Returns a list of all possible errors returned by the module
         * @return array in the format of array( key, param1, param2, ... ) or array( 'code' => ..., 'info' => ... )

diff --git a/includes/api/ApiLogin.php b/includes/api/ApiLogin.php
index fa57626..cf0666c 100644 (file)
--- a/includes/api/ApiLogin.php
+++ b/includes/api/ApiLogin.php
@@ -212,6 +212,10 @@ class ApiLogin extends ApiBase {
                );
        }
 
+       public function getHelpUrl() {
+               return 'http://www.mediawiki.org/wiki/API:Login';
+       }
+
        public function getVersion() {
                return __CLASS__ . ': $Id$';
        }

diff --git a/includes/api/ApiLogout.php b/includes/api/ApiLogout.php
index 244c976..9921c0d 100644 (file)
--- a/includes/api/ApiLogout.php
+++ b/includes/api/ApiLogout.php
@@ -73,6 +73,10 @@ class ApiLogout extends ApiBase {
                );
        }
 
+       public function getHelpUrl() {
+               return 'http://www.mediawiki.org/wiki/API:Logout';
+       }
+
        public function getVersion() {
                return __CLASS__ . ': $Id$';
        }

diff --git a/includes/api/ApiParamInfo.php b/includes/api/ApiParamInfo.php
index 95ff7bf..323c36f 100644 (file)
--- a/includes/api/ApiParamInfo.php
+++ b/includes/api/ApiParamInfo.php
@@ -94,6 +94,7 @@ class ApiParamInfo extends ApiBase {
                $retval['classname'] = get_class( $obj );
                $retval['description'] = implode( "\n", (array)$obj->getDescription() );
                $retval['examples'] = implode( "\n", (array)$obj->getExamples() );
+               $retval['helpurl'] = implode( "\n", (array)$obj->getHelpUrl() );
                $retval['version'] = implode( "\n", (array)$obj->getVersion() );
                $retval['prefix'] = $obj->getModulePrefix();
 
@@ -238,6 +239,10 @@ class ApiParamInfo extends ApiBase {
                );
        }
 
+       public function getHelpUrl() {
+               return 'http://www.mediawiki.org/wiki/API:Parameter_information';
+       }
+
        public function getVersion() {
                return __CLASS__ . ': $Id$';
        }

diff --git a/includes/api/ApiQuery.php b/includes/api/ApiQuery.php
index 810fba1..66b196b 100644 (file)
--- a/includes/api/ApiQuery.php
+++ b/includes/api/ApiQuery.php
@@ -702,6 +702,14 @@ class ApiQuery extends ApiBase {
                );
        }
 
+       public function getHelpUrl() {
+               return array(
+                       'http://www.mediawiki.org/wiki/API:Meta',
+                       'http://www.mediawiki.org/wiki/API:Properties',
+                       'http://www.mediawiki.org/wiki/API:Lists',
+               );
+       }
+
        public function getVersion() {
                $psModule = new ApiPageSet( $this );
                $vers = array();