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
This commit is contained in:
Brad Jorsch
Legoktm
parent
941b7a5c60
commit
c4ba6f9ecf
4 changed files with 51 additions and 7 deletions
|
|
@ -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,7 +528,24 @@ 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();
|
||||
}
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -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();
|
||||
|
|
|
|||
|
|
@ -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.",
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
|
|
|
|||
Loading…
Reference in a new issue