From 6c80c5ff87e913efab0a9a3a5541fa72c6071599 Mon Sep 17 00:00:00 2001
From: Sam Reed <reedy@users.mediawiki.org>
Date: Fri, 16 Dec 2011 15:28:35 +0000
Subject: [PATCH] Prep work for * (bug 33147) API examples should explain what
 they do

Now formatted in the autogenerated documentation

Format for paraminfo adds a description attribute to output


query allimages descriptions are tranformed, need to do/add to other ones
---
 RELEASE-NOTES-1.19                 |  1 +
 includes/api/ApiBase.php           | 32 +++++++++++++++++++++++++++++-
 includes/api/ApiParamInfo.php      | 30 +++++++++++++++++++++++-----
 includes/api/ApiQueryAllimages.php | 14 +++++++------
 4 files changed, 65 insertions(+), 12 deletions(-)

diff --git a/RELEASE-NOTES-1.19 b/RELEASE-NOTES-1.19
index e34014b705..d2e9b9943f 100644
--- a/RELEASE-NOTES-1.19
+++ b/RELEASE-NOTES-1.19
@@ -212,6 +212,7 @@ production.
 * (bug 32415) Empty page get no size attribute in API output.
 * (bug 31759) Undefined property notice in querypages API.
 * (bug 32495) API should allow purge by pageids.
+* (bug 33147) API examples should explain what they do.
 
 === Languages updated in 1.19 ===
 
diff --git a/includes/api/ApiBase.php b/includes/api/ApiBase.php
index e1ba493ff3..efbf1c0f11 100644
--- a/includes/api/ApiBase.php
+++ b/includes/api/ApiBase.php
@@ -267,7 +267,29 @@ abstract class ApiBase extends ContextSource {
 				$msg .= "Parameters:\n$paramsMsg";
 			}
 
-			$msg .= $this->makeHelpArrayToString( $lnPrfx, "Example", $this->getExamples() );
+			$examples = $this->getExamples();
+			if ( $examples !== false ) {
+				if ( !is_array( $examples ) ) {
+					$examples = array(
+						$examples
+					);
+				}
+				$msg .= "Example" . ( count( $examples ) > 1 ? 's' : '' ) . ":\n";
+				foreach( $examples as $k => $v ) {
+					if ( is_numeric( $k ) ) {
+						$msg .= "  $v\n";
+					} else {
+						if ( is_array( $v ) ) {
+							$msg .= implode( "\n", array_map( array( $this, 'indentExampleText' ), $v ) );
+						} else {
+							$msg .= "  $v";
+						}
+						$msg .= "\n    $k";
+					}
+				}
+			}
+
+			$msg .= "\n";
 			$msg .= $this->makeHelpArrayToString( $lnPrfx, "Help page", $this->getHelpUrls() );
 
 			if ( $this->getMain()->getShowVersions() ) {
@@ -291,6 +313,14 @@ abstract class ApiBase extends ContextSource {
 		return $msg;
 	}
 
+	/**
+	 * @param $item string
+	 * @return string
+	 */
+	private function indentExampleText( $item ) {
+		return "  " . $item;
+	}
+
 	/**
 	 * @param $prefix string Text to split output items
 	 * @param $title string What is being output
diff --git a/includes/api/ApiParamInfo.php b/includes/api/ApiParamInfo.php
index fd680620e3..42df86d250 100644
--- a/includes/api/ApiParamInfo.php
+++ b/includes/api/ApiParamInfo.php
@@ -114,8 +114,9 @@ class ApiParamInfo extends ApiBase {
 		$result = $this->getResult();
 		$retval['classname'] = get_class( $obj );
 		$retval['description'] = implode( "\n", (array)$obj->getFinalDescription() );
-		$examples = (array)$obj->getExamples();
-		$retval['examples'] = implode( "\n", $examples );
+
+		$retval['examples'] = '';
+
 		$retval['version'] = implode( "\n", (array)$obj->getVersion() );
 		$retval['prefix'] = $obj->getModulePrefix();
 
@@ -143,9 +144,28 @@ class ApiParamInfo extends ApiBase {
 		}
 		$result->setIndexedTagName( $retval['helpurls'], 'helpurl' );
 
-		$retval['allexamples'] = $examples;
-		if ( isset( $retval['allexamples'][0] ) && $retval['allexamples'][0] === false ) {
-			$retval['allexamples'] = array();
+		$examples = $obj->getExamples();
+		$retval['allexamples'] = array();
+		if ( $examples !== false ) {
+			foreach( $examples as $k => $v ) {
+				if ( strlen( $retval['examples'] ) ) {
+					$retval['examples'] .= ' ';
+				}
+				$item = array();
+				if ( is_numeric( $k ) ) {
+					$retval['examples'] .= $v;
+					$result->setContent( $item, $v );
+				} else {
+					if ( !is_array( $v ) ) {
+						$item['description'] = $v;
+					} else {
+						$item['description'] = implode( $v, "\n" );
+					}
+					$retval['examples'] .= $item['description'] . ' ' . $k;
+					$result->setContent( $item, $k );
+				}
+				$retval['allexamples'][] = $item;
+			}
 		}
 		$result->setIndexedTagName( $retval['allexamples'], 'example' );
 
diff --git a/includes/api/ApiQueryAllimages.php b/includes/api/ApiQueryAllimages.php
index c39f93a18e..ca344f7337 100644
--- a/includes/api/ApiQueryAllimages.php
+++ b/includes/api/ApiQueryAllimages.php
@@ -246,12 +246,14 @@ class ApiQueryAllimages extends ApiQueryGeneratorBase {
 
 	public function getExamples() {
 		return array(
-			'Simple Use',
-			' Show a list of images starting at the letter "B"',
-			'  api.php?action=query&list=allimages&aifrom=B',
-			'Using as Generator',
-			' Show info about 4 images starting at the letter "T"',
-			'  api.php?action=query&generator=allimages&gailimit=4&gaifrom=T&prop=imageinfo',
+			'api.php?action=query&list=allimages&aifrom=B' => array(
+				'Simple Use',
+				'Show a list of images starting at the letter "B"',
+			),
+			'api.php?action=query&generator=allimages&gailimit=4&gaifrom=T&prop=imageinfo' => array(
+				'Using as Generator',
+				'Show info about 4 images starting at the letter "T"',
+			),
 		);
 	}
 
-- 
2.20.1