jenkins-bot has submitted this change and it was merged.
Change subject: API: Document parameter types
......................................................................
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
---
M includes/api/ApiHelp.php
M includes/api/ApiMain.php
M includes/api/i18n/en.json
M includes/api/i18n/qqq.json
4 files changed, 51 insertions(+), 7 deletions(-)
Approvals:
Legoktm: Looks good to me, approved
jenkins-bot: Verified
diff --git a/includes/api/ApiHelp.php b/includes/api/ApiHelp.php
index 00fc12e..1e30616 100644
--- a/includes/api/ApiHelp.php
+++ b/includes/api/ApiHelp.php
@@ -164,17 +164,17 @@
$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 @@
->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 @@
->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 @@
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();
}
}
diff --git a/includes/api/ApiMain.php b/includes/api/ApiMain.php
index 465025c..7e3dcff 100644
--- a/includes/api/ApiMain.php
+++ b/includes/api/ApiMain.php
@@ -1305,6 +1305,7 @@
}
$help[$k] = $v;
}
+ $help['datatypes'] = '';
$help['credits'] = '';
// Fill 'permissions'
@@ -1337,10 +1338,18 @@
$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
--- 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
--- 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",
--
To view, visit https://gerrit.wikimedia.org/r/199982
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: merged
Gerrit-Change-Id: I67da4f4c026616eed5669256b208b03350e756c0
Gerrit-PatchSet: 3
Gerrit-Project: mediawiki/core
Gerrit-Branch: master
Gerrit-Owner: Anomie <[email protected]>
Gerrit-Reviewer: Legoktm <[email protected]>
Gerrit-Reviewer: Siebrand <[email protected]>
Gerrit-Reviewer: Spage <[email protected]>
Gerrit-Reviewer: jenkins-bot <>
_______________________________________________
MediaWiki-commits mailing list
[email protected]
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
