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

diff --git a/RELEASE-NOTES-1.19 b/RELEASE-NOTES-1.19
index e34014b..d2e9b99 100644 (file)
--- 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 e1ba493..efbf1c0 100644 (file)
--- 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 fd68062..42df86d 100644 (file)
--- 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 c39f93a..ca344f7 100644 (file)
--- 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"',
+                       ),
                );
        }