| Index: trunk/phase3/RELEASE-NOTES-1.19 |
| — | — | @@ -212,6 +212,7 @@ |
| 213 | 213 | * (bug 32415) Empty page get no size attribute in API output. |
| 214 | 214 | * (bug 31759) Undefined property notice in querypages API. |
| 215 | 215 | * (bug 32495) API should allow purge by pageids. |
| | 216 | +* (bug 33147) API examples should explain what they do. |
| 216 | 217 | |
| 217 | 218 | === Languages updated in 1.19 === |
| 218 | 219 | |
| Index: trunk/phase3/includes/api/ApiQueryAllimages.php |
| — | — | @@ -246,12 +246,14 @@ |
| 247 | 247 | |
| 248 | 248 | public function getExamples() { |
| 249 | 249 | return array( |
| 250 | | - 'Simple Use', |
| 251 | | - ' Show a list of images starting at the letter "B"', |
| 252 | | - ' api.php?action=query&list=allimages&aifrom=B', |
| 253 | | - 'Using as Generator', |
| 254 | | - ' Show info about 4 images starting at the letter "T"', |
| 255 | | - ' api.php?action=query&generator=allimages&gailimit=4&gaifrom=T&prop=imageinfo', |
| | 250 | + 'api.php?action=query&list=allimages&aifrom=B' => array( |
| | 251 | + 'Simple Use', |
| | 252 | + 'Show a list of images starting at the letter "B"', |
| | 253 | + ), |
| | 254 | + 'api.php?action=query&generator=allimages&gailimit=4&gaifrom=T&prop=imageinfo' => array( |
| | 255 | + 'Using as Generator', |
| | 256 | + 'Show info about 4 images starting at the letter "T"', |
| | 257 | + ), |
| 256 | 258 | ); |
| 257 | 259 | } |
| 258 | 260 | |
| Index: trunk/phase3/includes/api/ApiBase.php |
| — | — | @@ -267,7 +267,29 @@ |
| 268 | 268 | $msg .= "Parameters:\n$paramsMsg"; |
| 269 | 269 | } |
| 270 | 270 | |
| 271 | | - $msg .= $this->makeHelpArrayToString( $lnPrfx, "Example", $this->getExamples() ); |
| | 271 | + $examples = $this->getExamples(); |
| | 272 | + if ( $examples !== false ) { |
| | 273 | + if ( !is_array( $examples ) ) { |
| | 274 | + $examples = array( |
| | 275 | + $examples |
| | 276 | + ); |
| | 277 | + } |
| | 278 | + $msg .= "Example" . ( count( $examples ) > 1 ? 's' : '' ) . ":\n"; |
| | 279 | + foreach( $examples as $k => $v ) { |
| | 280 | + if ( is_numeric( $k ) ) { |
| | 281 | + $msg .= " $v\n"; |
| | 282 | + } else { |
| | 283 | + if ( is_array( $v ) ) { |
| | 284 | + $msg .= implode( "\n", array_map( array( $this, 'indentExampleText' ), $v ) ); |
| | 285 | + } else { |
| | 286 | + $msg .= " $v"; |
| | 287 | + } |
| | 288 | + $msg .= "\n $k"; |
| | 289 | + } |
| | 290 | + } |
| | 291 | + } |
| | 292 | + |
| | 293 | + $msg .= "\n"; |
| 272 | 294 | $msg .= $this->makeHelpArrayToString( $lnPrfx, "Help page", $this->getHelpUrls() ); |
| 273 | 295 | |
| 274 | 296 | if ( $this->getMain()->getShowVersions() ) { |
| — | — | @@ -292,6 +314,14 @@ |
| 293 | 315 | } |
| 294 | 316 | |
| 295 | 317 | /** |
| | 318 | + * @param $item string |
| | 319 | + * @return string |
| | 320 | + */ |
| | 321 | + private function indentExampleText( $item ) { |
| | 322 | + return " " . $item; |
| | 323 | + } |
| | 324 | + |
| | 325 | + /** |
| 296 | 326 | * @param $prefix string Text to split output items |
| 297 | 327 | * @param $title string What is being output |
| 298 | 328 | * @param $input string|array |
| Index: trunk/phase3/includes/api/ApiParamInfo.php |
| — | — | @@ -114,8 +114,9 @@ |
| 115 | 115 | $result = $this->getResult(); |
| 116 | 116 | $retval['classname'] = get_class( $obj ); |
| 117 | 117 | $retval['description'] = implode( "\n", (array)$obj->getFinalDescription() ); |
| 118 | | - $examples = (array)$obj->getExamples(); |
| 119 | | - $retval['examples'] = implode( "\n", $examples ); |
| | 118 | + |
| | 119 | + $retval['examples'] = ''; |
| | 120 | + |
| 120 | 121 | $retval['version'] = implode( "\n", (array)$obj->getVersion() ); |
| 121 | 122 | $retval['prefix'] = $obj->getModulePrefix(); |
| 122 | 123 | |
| — | — | @@ -143,9 +144,28 @@ |
| 144 | 145 | } |
| 145 | 146 | $result->setIndexedTagName( $retval['helpurls'], 'helpurl' ); |
| 146 | 147 | |
| 147 | | - $retval['allexamples'] = $examples; |
| 148 | | - if ( isset( $retval['allexamples'][0] ) && $retval['allexamples'][0] === false ) { |
| 149 | | - $retval['allexamples'] = array(); |
| | 148 | + $examples = $obj->getExamples(); |
| | 149 | + $retval['allexamples'] = array(); |
| | 150 | + if ( $examples !== false ) { |
| | 151 | + foreach( $examples as $k => $v ) { |
| | 152 | + if ( strlen( $retval['examples'] ) ) { |
| | 153 | + $retval['examples'] .= ' '; |
| | 154 | + } |
| | 155 | + $item = array(); |
| | 156 | + if ( is_numeric( $k ) ) { |
| | 157 | + $retval['examples'] .= $v; |
| | 158 | + $result->setContent( $item, $v ); |
| | 159 | + } else { |
| | 160 | + if ( !is_array( $v ) ) { |
| | 161 | + $item['description'] = $v; |
| | 162 | + } else { |
| | 163 | + $item['description'] = implode( $v, "\n" ); |
| | 164 | + } |
| | 165 | + $retval['examples'] .= $item['description'] . ' ' . $k; |
| | 166 | + $result->setContent( $item, $k ); |
| | 167 | + } |
| | 168 | + $retval['allexamples'][] = $item; |
| | 169 | + } |
| 150 | 170 | } |
| 151 | 171 | $result->setIndexedTagName( $retval['allexamples'], 'example' ); |
| 152 | 172 | |