From d18c0dc3155d3d9f0c70549c61af915ad4844a7b Mon Sep 17 00:00:00 2001
From: Sam Reed <reedy@users.mediawiki.org>
Date: Sun, 17 Jul 2011 16:18:09 +0000
Subject: [PATCH] * (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
---
 includes/api/ApiBase.php      | 54 +++++++++++++++++++++++------------
 includes/api/ApiLogin.php     |  4 +++
 includes/api/ApiLogout.php    |  4 +++
 includes/api/ApiParamInfo.php |  5 ++++
 includes/api/ApiQuery.php     |  8 ++++++
 5 files changed, 57 insertions(+), 18 deletions(-)

diff --git a/includes/api/ApiBase.php b/includes/api/ApiBase.php
index 8fbeb1264d..360efdaf5a 100644
--- 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 fa576266c1..cf0666ccea 100644
--- 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 244c976c3d..9921c0dbdd 100644
--- 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 95ff7bf0e9..323c36f837 100644
--- 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 810fba1e6d..66b196bb45 100644
--- 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();
-- 
2.20.1