From e0df93d890a9e705cd8581eb908c49ea0f146596 Mon Sep 17 00:00:00 2001 From: Lucas Werkmeister Date: Tue, 5 Nov 2024 11:55:33 +0100 Subject: [PATCH] Document available wbformatvalue options MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit We’re about to declare other formatter options unsupported (change Ifd1367eaff), so it stands to reason that the four validated options are supported, part of the stable interface, and should be documented. I first thought about putting this in docs/topics/, but I don’t think it really fits there (and it would be confusing with the already existing docs/topics/options.md). I think the parameter documentation works pretty well (Special:ApiSandbox even makes the definition list collapsable automatically), and there’s robust support for customizing it and adding additional parameters (to avoid repeating the option names – though they’re still part of the stable interface and can’t easily be renamed, of course) both in ApiBase and in {{doc-apihelp-param}}. Bug: T323778 Change-Id: I92931f3ddeef97ec22f89869c687f63f9fb596cc --- repo/i18n/api/en.json | 2 +- repo/i18n/api/qqq.json | 2 +- repo/includes/Api/FormatSnakValue.php | 7 +++++++ 3 files changed, 9 insertions(+), 2 deletions(-) diff --git a/repo/i18n/api/en.json b/repo/i18n/api/en.json index d891918e73c..316cf8aa857 100644 --- a/repo/i18n/api/en.json +++ b/repo/i18n/api/en.json @@ -73,7 +73,7 @@ "apihelp-wbformatvalue-param-generate": "The desired output format to generate.", "apihelp-wbformatvalue-param-datatype": "The value's data type. This is distinct from the value's type", "apihelp-wbformatvalue-param-datavalue": "The data to format. This has to be the JSON serialization of a DataValue object.", - "apihelp-wbformatvalue-param-options": "The options the formatter should use. Provided as a JSON object.", + "apihelp-wbformatvalue-param-options": "The options the formatter should use. Provided as a JSON object.\n\nThe supported options are:\n; $1: The language in which the value should be formatted (a MediaWiki language code).\n; $2: Whether to apply rounding to the number. Can be a boolean (automatic / no rounding) or an integer (exponent of the last significant decimal digits). Only useful for quantity values.\n; $3: Whether to include the unit in the output (a boolean). Only useful for quantity values.\n; $4: Whether to show the calendar model. Can be a boolean (always / never show) or the string \"auto\" (automatically determine whether to show). Only useful for time values.", "apihelp-wbformatvalue-param-property": "Property ID the data value belongs to, should be used instead of the datatype parameter.", "apihelp-wbformatvalue-example-1": "Format a simple string value.", "apihelp-wbformatvalue-example-2": "Format a string value as a URL in HTML.", diff --git a/repo/i18n/api/qqq.json b/repo/i18n/api/qqq.json index 471e1c43d63..d047c5bf866 100644 --- a/repo/i18n/api/qqq.json +++ b/repo/i18n/api/qqq.json @@ -96,7 +96,7 @@ "apihelp-wbformatvalue-param-generate": "{{doc-apihelp-param|wbformatvalue|generate}}", "apihelp-wbformatvalue-param-datatype": "{{doc-apihelp-param|wbformatvalue|datatype}}", "apihelp-wbformatvalue-param-datavalue": "{{doc-apihelp-param|wbformatvalue|datavalue}}", - "apihelp-wbformatvalue-param-options": "{{doc-apihelp-param|wbformatvalue|options}}", + "apihelp-wbformatvalue-param-options": "{{doc-apihelp-param|wbformatvalue|options|params=* $1, $2, $3, $4 - The names of the four supported options|paramstart=5}}", "apihelp-wbformatvalue-param-property": "{{doc-apihelp-param|wbformatvalue|property}}", "apihelp-wbformatvalue-example-1": "{{doc-apihelp-example|wbformatvalue}}", "apihelp-wbformatvalue-example-2": "{{doc-apihelp-example|wbformatvalue}}", diff --git a/repo/includes/Api/FormatSnakValue.php b/repo/includes/Api/FormatSnakValue.php index 5905b4d6285..296d4b6dcca 100644 --- a/repo/includes/Api/FormatSnakValue.php +++ b/repo/includes/Api/FormatSnakValue.php @@ -362,6 +362,13 @@ protected function getAllowedParams(): array { 'options' => [ ParamValidator::PARAM_TYPE => 'text', ParamValidator::PARAM_REQUIRED => false, + ApiBase::PARAM_HELP_MSG => [ + 'apihelp-wbformatvalue-param-options', + ValueFormatter::OPT_LANG, + QuantityFormatter::OPT_APPLY_ROUNDING, + QuantityFormatter::OPT_APPLY_UNIT, + ShowCalendarModelDecider::OPT_SHOW_CALENDAR, + ], ], ]; }