From: Brad Jorsch Date: Thu, 26 Mar 2015 19:34:55 +0000 (-0400) Subject: API: Document parameter types X-Git-Tag: 1.31.0-rc.0~11679 X-Git-Url: http://git.heureux-cyclage.org/?a=commitdiff_plain;h=c4ba6f9ecf5f76a62e3d5f188f97c98e5e788bc2;p=lhc%2Fweb%2Fwiklou.git 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 00fc12ef0b..1e306163fb 100644 --- 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 465025c93e..7e3dcff2ee 100644 --- 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 ee66238312..615d60a9cd 100644 --- 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, 2001-01-15T14:56:00Z (punctuation and Z are optional)\n:* ISO 8601 date and time with (ignored) fractional seconds, 2001-01-15T14:56:00.00001Z (dashes, colons, and Z are optional)\n:* MediaWiki format, 20010115145600\n:* Generic numeric format, 2001-01-15 14:56:00 (optional timezone of GMT, +##, or -## is ignored)\n:* EXIF format, 2001:01:15 14:56:00\n:*RFC 2822 format (timezone may be omitted), Mon, 15 Jan 2001 14:56:00\n:* RFC 850 format (timezone may be omitted), Monday, 15-Jan-2001 14:56:00\n:* C ctime format, Mon Jan 15 14:56:00 2001\n:* Seconds since 1970-01-01T00:00:00Z as a 1 to 13 digit integer", + "api-help-param-type-limit": "Type: integer or max", + "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 {{!}})}}: $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 d2c6ec9328..876f598083 100644 --- 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 Special:ApiHelp 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 Special:ApiHelp 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",