From f3839fe71fb5785f9fdbff43f8f9e9054d416c22 Mon Sep 17 00:00:00 2001
From: Sam Reed <reedy@users.mediawiki.org>
Date: Mon, 28 Nov 2011 15:33:28 +0000
Subject: [PATCH] Added "ApiGetDescription" hook

---
 RELEASE-NOTES-1.19            |  1 +
 docs/hooks.txt                |  8 ++++++--
 includes/api/ApiBase.php      | 18 ++++++++++++++++--
 includes/api/ApiParamInfo.php |  2 +-
 4 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/RELEASE-NOTES-1.19 b/RELEASE-NOTES-1.19
index 265617b68c..7620f2bcc0 100644
--- a/RELEASE-NOTES-1.19
+++ b/RELEASE-NOTES-1.19
@@ -184,6 +184,7 @@ production.
   up as a redirect to the linked page on Special:Whatlinkshere.
 * (bug 32609) API: Move captchaid/captchaword of action=edit from core
   to Captcha extension(s)
+* Added 'ApiGetDescription' hook.
 
 === Languages updated in 1.19 ===
 
diff --git a/docs/hooks.txt b/docs/hooks.txt
index 6c7c48ef0f..8223ef17c7 100644
--- a/docs/hooks.txt
+++ b/docs/hooks.txt
@@ -319,12 +319,16 @@ $text : the new text of the article (has yet to be saved)
 &$resultArr : data in this array will be added to the API result
 
 'APIGetAllowedParams': use this hook to modify a module's parameters.
-&$module: Module object
+&$module: ApiBase Module object
 &$params: Array of parameters
 
+'APIGetDescription': use this hook to modify a module's description
+&$module: ApiBase Module object
+&$desc: Array of descriptions
+
 'APIGetParamDescription': use this hook to modify a module's parameter
 descriptions.
-&$module: Module object
+&$module: ApiBase Module object
 &$desc: Array of parameter descriptions
 
 'APIQueryAfterExecute': after calling the execute() method of an
diff --git a/includes/api/ApiBase.php b/includes/api/ApiBase.php
index 3613a6cc5d..cbf79d270b 100644
--- a/includes/api/ApiBase.php
+++ b/includes/api/ApiBase.php
@@ -235,7 +235,7 @@ abstract class ApiBase extends ContextSource {
 	public function makeHelpMsg() {
 		static $lnPrfx = "\n  ";
 
-		$msg = $this->getDescription();
+		$msg = $this->getFinalDescription();
 
 		if ( $msg !== false ) {
 
@@ -510,6 +510,7 @@ abstract class ApiBase extends ContextSource {
 	/**
 	 * Get final list of parameters, after hooks have had a chance to
 	 * tweak it as needed.
+	 *
 	 * @return array or false
 	 */
 	public function getFinalParams() {
@@ -519,8 +520,9 @@ abstract class ApiBase extends ContextSource {
 	}
 
 	/**
-	 * Get final description, after hooks have had a chance to tweak it as
+	 * Get final parameter descriptions, after hooks have had a chance to tweak it as
 	 * needed.
+	 *
 	 * @return array
 	 */
 	public function getFinalParamDescription() {
@@ -529,6 +531,18 @@ abstract class ApiBase extends ContextSource {
 		return $desc;
 	}
 
+	/**
+	 * Get final module description, after hooks have had a chance to tweak it as
+	 * needed.
+	 *
+	 * @return array
+	 */
+	public function getFinalDescription() {
+		$desc = $this->getDescription();
+		wfRunHooks( 'ApiGetDescription', array( &$this, &$desc ) );
+		return $desc;
+	}
+
 	/**
 	 * This method mangles parameter name based on the prefix supplied to the constructor.
 	 * Override this method to change parameter name during runtime
diff --git a/includes/api/ApiParamInfo.php b/includes/api/ApiParamInfo.php
index 72d424964a..8686ea9f80 100644
--- a/includes/api/ApiParamInfo.php
+++ b/includes/api/ApiParamInfo.php
@@ -113,7 +113,7 @@ class ApiParamInfo extends ApiBase {
 	function getClassInfo( $obj ) {
 		$result = $this->getResult();
 		$retval['classname'] = get_class( $obj );
-		$retval['description'] = implode( "\n", (array)$obj->getDescription() );
+		$retval['description'] = implode( "\n", (array)$obj->getFinalDescription() );
 		$examples = (array)$obj->getExamples();
 		$retval['examples'] = implode( "\n", $examples );
 		$retval['version'] = implode( "\n", (array)$obj->getVersion() );
-- 
2.20.1