API: Document parameter types

Two things here:
* Identify the parameter types when they're not simple strings (or
  already identified).
* Add a section to the 'main' module documentation that describes
  booleans and timestamp formats.

Bug: T93982
Bug: T47652
Change-Id: I67da4f4c026616eed5669256b208b03350e756c0

diff --git a/includes/api/ApiHelp.php b/includes/api/ApiHelp.php
index 00fc12e..1e30616 100644 (file)
--- a/includes/api/ApiHelp.php
+++ b/includes/api/ApiHelp.php
@@ -164,17 +164,17 @@ class ApiHelp extends ApiBase {
                                $old = $href;
                                $href = rawurldecode( $href );
                        } while ( $old !== $href );
-                       if ( preg_match( '!Special:ApiHelp/([^&/|]+)!', $href, $m ) ) {
+                       if ( preg_match( '!Special:ApiHelp/([^&/|#]+)((?:#.*)?)!', $href, $m ) ) {
                                if ( isset( $localModules[$m[1]] ) ) {
-                                       $href = '#' . $m[1];
+                                       $href = $m[2] === '' ? '#' . $m[1] : $m[2];
                                } elseif ( $helptitle !== null ) {
-                                       $href = Title::newFromText( str_replace( '$1', $m[1], $helptitle ) )
+                                       $href = Title::newFromText( str_replace( '$1', $m[1], $helptitle ) . $m[2] )
                                                ->getFullUrl();
                                } else {
                                        $href = wfAppendQuery( wfScript( 'api' ), array(
                                                'action' => 'help',
                                                'modules' => $m[1],
-                                       ) );
+                                       ) ) . $m[2];
                                }
                                $node->setAttribute( 'href', $href );
                                $node->removeAttribute( 'title' );
@@ -472,6 +472,8 @@ class ApiHelp extends ApiBase {
                                                                                ->params( $context->getLanguage()->commaList( $submodules ) )
                                                                                ->parse();
                                                                        $hintPipeSeparated = false;
+                                                                       // No type message necessary, we have a list of values.
+                                                                       $type = null;
                                                                        break;
 
                                                                case 'namespace':
@@ -482,6 +484,8 @@ class ApiHelp extends ApiBase {
                                                                                ->params( $context->getLanguage()->commaList( $namespaces ) )
                                                                                ->parse();
                                                                        $hintPipeSeparated = false;
+                                                                       // No type message necessary, we have a list of values.
+                                                                       $type = null;
                                                                        break;
 
                                                                case 'limit':
@@ -524,10 +528,27 @@ class ApiHelp extends ApiBase {
                                                                case 'upload':
                                                                        $info[] = $context->msg( 'api-help-param-upload' )
                                                                                ->parse();
+                                                                       // No type message necessary, api-help-param-upload should handle it.
+                                                                       $type = null;
+                                                                       break;
+
+                                                               case 'string':
+                                                                       // Displaying a type message here would be useless.
+                                                                       $type = null;
                                                                        break;
                                                        }
                                                }
 
+                                               // Add type. Messages for grep: api-help-param-type-limit
+                                               // api-help-param-type-integer api-help-param-type-boolean
+                                               // api-help-param-type-timestamp api-help-param-type-user
+                                               if ( is_string( $type ) ) {
+                                                       $msg = $context->msg( "api-help-param-type-$type" );
+                                                       if ( !$msg->isDisabled() ) {
+                                                               $info[] = $msg->params( $multi ? 2 : 1 )->parse();
+                                                       }
+                                               }
+
                                                if ( $multi ) {
                                                        $extra = array();
                                                        if ( $hintPipeSeparated ) {

diff --git a/includes/api/ApiMain.php b/includes/api/ApiMain.php
index 465025c..7e3dcff 100644 (file)
--- a/includes/api/ApiMain.php
+++ b/includes/api/ApiMain.php
@@ -1305,6 +1305,7 @@ class ApiMain extends ApiBase {
                        }
                        $help[$k] = $v;
                }
+               $help['datatypes'] = '';
                $help['credits'] = '';
 
                // Fill 'permissions'
@@ -1337,10 +1338,18 @@ class ApiMain extends ApiBase {
                $help['permissions'] .= Html::closeElement( 'dl' );
                $help['permissions'] .= Html::closeElement( 'div' );
 
-               // Fill 'credits', if applicable
+               // Fill 'datatypes' and 'credits', if applicable
                if ( empty( $options['nolead'] ) ) {
-                       $help['credits'] .= Html::element( 'h' . min( 6, $options['headerlevel'] + 1 ),
-                               array( 'id' => '+credits', 'class' => 'apihelp-header' ),
+                       $help['datatypes'] .= Html::rawelement( 'h' . min( 6, $options['headerlevel'] + 1 ),
+                               array( 'id' => 'main/datatypes', 'class' => 'apihelp-header' ),
+                               Html::element( 'span', array( 'id' => Sanitizer::escapeId( 'main/datatypes' ) ) ) .
+                               $this->msg( 'api-help-datatypes-header' )->parse()
+                       );
+                       $help['datatypes'] .= $this->msg( 'api-help-datatypes' )->parseAsBlock();
+
+                       $help['credits'] .= Html::rawelement( 'h' . min( 6, $options['headerlevel'] + 1 ),
+                               array( 'id' => 'main/credits', 'class' => 'apihelp-header' ),
+                               Html::element( 'span', array( 'id' => Sanitizer::escapeId( 'main/credits' ) ) ) .
                                $this->msg( 'api-credits-header' )->parse()
                        );
                        $help['credits'] .= $this->msg( 'api-credits' )->useDatabase( false )->parseAsBlock();

diff --git a/includes/api/i18n/en.json b/includes/api/i18n/en.json
index ee66238..615d60a 100644 (file)
--- a/includes/api/i18n/en.json
+++ b/includes/api/i18n/en.json
@@ -1144,6 +1144,13 @@
        "api-help-parameters": "{{PLURAL:$1|Parameter|Parameters}}:",
        "api-help-param-deprecated": "Deprecated.",
        "api-help-param-required": "This parameter is required.",
+       "api-help-datatypes-header": "Data types",
+       "api-help-datatypes": "Some API parameter types need further explanation:\n;boolean\n:Boolean parameters work like HTML checkboxes: if the parameter is specified, regardless of value, it is considered true. For a false value, omit the parameter entirely.\n;timestamp\n:Timestamps may be specified in several formats. ISO 8601 date and time is recommended. All times are in UTC, any included timezone is ignored.\n:* ISO 8601 date and time, <kbd><var>2001</var>-<var>01</var>-<var>15</var>T<var>14</var>:<var>56</var>:<var>00</var>Z</kbd> (punctuation and <kbd>Z</kbd> are optional)\n:* ISO 8601 date and time with (ignored) fractional seconds, <kbd><var>2001</var>-<var>01</var>-<var>15</var>T<var>14</var>:<var>56</var>:<var>00</var>.<var>00001</var>Z</kbd> (dashes, colons, and <kbd>Z</kbd> are optional)\n:* MediaWiki format, <kbd><var>2001</var><var>01</var><var>15</var><var>14</var><var>56</var><var>00</var></kbd>\n:* Generic numeric format, <kbd><var>2001</var>-<var>01</var>-<var>15</var> <var>14</var>:<var>56</var>:<var>00</var></kbd> (optional timezone of <kbd>GMT</kbd>, <kbd>+<var>##</var></kbd>, or <kbd>-<var>##</var></kbd> is ignored)\n:* EXIF format, <kbd><var>2001</var>:<var>01</var>:<var>15</var> <var>14</var>:<var>56</var>:<var>00</var></kbd>\n:*RFC 2822 format (timezone may be omitted), <kbd><var>Mon</var>, <var>15</var> <var>Jan</var> <var>2001</var> <var>14</var>:<var>56</var>:<var>00</var></kbd>\n:* RFC 850 format (timezone may be omitted), <kbd><var>Monday</var>, <var>15</var>-<var>Jan</var>-<var>2001</var> <var>14</var>:<var>56</var>:<var>00</var></kbd>\n:* C ctime format, <kbd><var>Mon</var> <var>Jan</var> <var>15</var> <var>14</var>:<var>56</var>:<var>00</var> <var>2001</var></kbd>\n:* Seconds since 1970-01-01T00:00:00Z as a 1 to 13 digit integer",
+       "api-help-param-type-limit": "Type: integer or <kbd>max</kbd>",
+       "api-help-param-type-integer": "Type: {{PLURAL:$1|1=integer|2=list of integers}}",
+       "api-help-param-type-boolean": "Type: boolean ([[Special:ApiHelp/main#main/datatypes|details]])",
+       "api-help-param-type-timestamp": "Type: {{PLURAL:$1|1=timestamp|2=list of timestamps}} ([[Special:ApiHelp/main#main/datatypes|allowed formats]])",
+       "api-help-param-type-user": "Type: {{PLURAL:$1|1=user name|2=list of user names}}",
        "api-help-param-list": "{{PLURAL:$1|1=One value|2=Values (separate with <kbd>{{!}}</kbd>)}}: $2",
        "api-help-param-list-can-be-empty": "{{PLURAL:$1|0=Must be empty|Can be empty, or $2}}",
        "api-help-param-limit": "No more than $1 allowed.",

diff --git a/includes/api/i18n/qqq.json b/includes/api/i18n/qqq.json
index d2c6ec9..876f598 100644 (file)
--- a/includes/api/i18n/qqq.json
+++ b/includes/api/i18n/qqq.json
@@ -1045,6 +1045,13 @@
        "api-help-parameters": "Label for the API help parameters section\n\nParameters:\n* $1 - Number of parameters to be displayed\n{{Identical|Parameter}}",
        "api-help-param-deprecated": "Displayed in the API help for any deprecated parameter\n{{Identical|Deprecated}}",
        "api-help-param-required": "Displayed in the API help for any required parameter",
+       "api-help-datatypes-header": "Header for the data type section in the API help output",
+       "api-help-datatypes": "{{technical}} {{doc-important|Do not translate or reformat dates inside <kbd%gt; tags}} Documentation of certain API data types\nSee also:\n* [[Special:PrefixIndex/MediaWiki:api-help-param-type]]",
+       "api-help-param-type-limit": "{{technical}} {{doc-important|Do not translate text inside <kbd%gt; tags}} Used to indicate that a parameter is a \"limit\" type. Parameters:\n* $1 - Always 1.\nSee also:\n* {{msg-mw|api-help-datatypes}}\n* [[Special:PrefixIndex/MediaWiki:api-help-param-type]]",
+       "api-help-param-type-integer": "{{technical}} Used to indicate that a parameter is an integer or list of integers. Parameters:\n* $1 - 1 if the parameter takes one value, 2 if the parameter takes a list of values.\nSee also:\n* {{msg-mw|api-help-datatypes}}\n* [[Special:PrefixIndex/MediaWiki:api-help-param-type]]",
+       "api-help-param-type-boolean": "{{technical}} {{doc-important|Do not translate <code>Special:ApiHelp</code> in this message.}} Used to indicate that a parameter is a boolean. Parameters:\n* $1 - Always 1.\nSee also:\n* {{msg-mw|api-help-datatypes}}\n* [[Special:PrefixIndex/MediaWiki:api-help-param-type]]",
+       "api-help-param-type-timestamp": "{{technical}} {{doc-important|Do not translate <code>Special:ApiHelp</code> in this message.}} Used to indicate that a parameter is a timestamp or list of timestamps. Parameters:\n* $1 - 1 if the parameter takes one value, 2 if the parameter takes a list of values.\nSee also:\n* {{msg-mw|api-help-datatypes}}\n* [[Special:PrefixIndex/MediaWiki:api-help-param-type]]",
+       "api-help-param-type-user": "{{technical}} Used to indicate that a parameter is a username or list of usernames. Parameters:\n* $1 - 1 if the parameter takes one value, 2 if the parameter takes a list of values.\nSee also:\n* {{msg-mw|api-help-datatypes}}\n* [[Special:PrefixIndex/MediaWiki:api-help-param-type]]",
        "api-help-param-list": "Used to display the possible values for a parameter taking a list of values\n\nParameters:\n* $1 - 1 if the parameter takes one value, 2 if the parameter takes any number of values\n* $2 - Comma-separated list of values, possibly formatted using {{msg-mw|api-help-param-list-can-be-empty}}\n{{Identical|Value}}",
        "api-help-param-list-can-be-empty": "Used to indicate that one of the possible values in the list is the empty string.\n\nParameters:\n* $1 - Number of items in the rest of the list; may be 0\n* $2 - Remainder of the list as a comma-separated string",
        "api-help-param-limit": "Used to display the maximum value of a limit parameter\n\nParameters:\n* $1 - Maximum value",