From ede1d19076937a72b11b420a5f675f7a18a826dc Mon Sep 17 00:00:00 2001
From: Brad Jorsch <bjorsch@wikimedia.org>
Date: Fri, 15 Jan 2016 16:38:31 -0500
Subject: [PATCH] API: Add support for documenting dynamic parameters

This will be used by AuthManager's API modules to document the fact that
AuthenticationRequest fields are accepted by the module, and to inform
the user reading the documentation how to determine what those are at
any particular time.

Change-Id: Ic7351de0f9bd239db17d584196e52a77112ed978
---
 includes/api/ApiBase.php      | 11 +++++++++++
 includes/api/ApiHelp.php      | 14 +++++++++++++-
 includes/api/ApiParamInfo.php | 14 ++++++++++++++
 3 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/includes/api/ApiBase.php b/includes/api/ApiBase.php
index 5f67a2265a..13d13a6853 100644
--- a/includes/api/ApiBase.php
+++ b/includes/api/ApiBase.php
@@ -637,6 +637,17 @@ abstract class ApiBase extends ContextSource {
 	 * @{
 	 */
 
+	/**
+	 * Indicate if the module supports dynamically-determined parameters that
+	 * cannot be included in self::getAllowedParams().
+	 * @return string|array|Message|null Return null if the module does not
+	 *  support additional dynamic parameters, otherwise return a message
+	 *  describing them.
+	 */
+	public function dynamicParameterDocumentation() {
+		return null;
+	}
+
 	/**
 	 * 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/ApiHelp.php b/includes/api/ApiHelp.php
index 9bbb0b00c0..bbea20b524 100644
--- a/includes/api/ApiHelp.php
+++ b/includes/api/ApiHelp.php
@@ -392,8 +392,9 @@ class ApiHelp extends ApiBase {
 			}
 
 			$params = $module->getFinalParams( ApiBase::GET_VALUES_FOR_HELP );
+			$dynamicParams = $module->dynamicParameterDocumentation();
 			$groups = array();
-			if ( $params ) {
+			if ( $params || $dynamicParams !== null ) {
 				$help['parameters'] .= Html::openElement( 'div',
 					array( 'class' => 'apihelp-block apihelp-parameters' )
 				);
@@ -654,6 +655,17 @@ class ApiHelp extends ApiBase {
 					}
 				}
 
+				if ( $dynamicParams !== null ) {
+					$dynamicParams = ApiBase::makeMessage( $dynamicParams, $context, array(
+						$module->getModulePrefix(),
+						$module->getModuleName(),
+						$module->getModulePath()
+					) );
+					$help['parameters'] .= Html::element( 'dt', null, '*' );
+					$help['parameters'] .= Html::rawElement( 'dd',
+						array( 'class' => 'description' ), $dynamicParams->parse() );
+				}
+
 				$help['parameters'] .= Html::closeElement( 'dl' );
 				$help['parameters'] .= Html::closeElement( 'div' );
 			}
diff --git a/includes/api/ApiParamInfo.php b/includes/api/ApiParamInfo.php
index a808ac0039..18ca0ab15c 100644
--- a/includes/api/ApiParamInfo.php
+++ b/includes/api/ApiParamInfo.php
@@ -387,6 +387,20 @@ class ApiParamInfo extends ApiBase {
 		}
 		ApiResult::setIndexedTagName( $ret['parameters'], 'param' );
 
+		$dynamicParams = $module->dynamicParameterDocumentation();
+		if ( $dynamicParams !== null ) {
+			if ( $this->helpFormat === 'none' ) {
+				$ret['dynamicparameters'] = true;
+			} else {
+				$dynamicParams = ApiBase::makeMessage( $dynamicParams, $this->context, array(
+					$module->getModulePrefix(),
+					$module->getModuleName(),
+					$module->getModulePath()
+				) );
+				$this->formatHelpMessages( $ret, 'dynamicparameters', array( $dynamicParams ) );
+			}
+		}
+
 		return $ret;
 	}
 
-- 
2.20.1