Page MenuHomePhabricator

Make better use of PARAM_HELP_MSG_PER_VALUE across all Wikimedia-deployed MediaWiki code
Open, Needs TriagePublic

Description

This is probably going to result in various subtasks and stuff (in extensions)... But as a replacement for T284451: Allow better documentation of Api allowed parameters, where parameters are a list of specific values, there are two things that need doing:

  1. Where a parameter "description" message is reused (such as apihelp-main-param-errorformat) to document the possible values, the documentation for these possible values should be split out into seperate messages
"apihelp-main-param-errorformat": "Format to use for warning and error text output.\n; plaintext: Wikitext with HTML tags removed and entities replaced.\n; wikitext: Unparsed wikitext.\n; html: HTML.\n; raw: Message key and parameters.\n; none: No text output, only the error codes.\n; bc: Format used prior to MediaWiki 1.29. <var>errorlang</var> and <var>errorsuselocal</var> are ignored.",

becomes

"apihelp-main-param-errorformat": "Format to use for warning and error text output",
"apihelp-main-paramvalue-errorformat-plaintext": "Wikitext with HTML tags removed and entities replaced.",
"apihelp-main-paramvalue-errorformat-wikitext": "Unparsed wikitext.",
"apihelp-main-paramvalue-errorformat-html": "HTML",
"apihelp-main-paramvalue-errorformat-raw": "Message key and parameters.",
"apihelp-main-paramvalue-errorformat-none": "No text output, only the error codes.",
"apihelp-main-paramvalue-errorformat-bc": "Format used prior to MediaWiki 1.29. <var>errorlang</var> and <var>errorsuselocal</var> are ignored.",
  1. Like has been done in T283040: Aspect values are poorly documented in API help pages, where an API parameter has a limited set of values (that potentially aren't immediately obvious what they mean), and isn't even documented like the above example of apihelp-main-param-errorformat, we should make make sure these have i18n messages (so they're translateable!) documenting what the different options mean, and set ApiBase::PARAM_HELP_MSG_PER_VALUE => [] on the appropriate getAllowedParams method.

There is possibly an outstanding question of whether ApiBase::PARAM_HELP_MSG_PER_VALUE => [] needs better documentation/visibility more generally, but this is potentially better addressed by just more wide and consistent usage, so people see it is there and can be used.

It is documented on mw.org at https://www.mediawiki.org/wiki/API:Localisation#Naming

Event Timeline

Based on "One of the following values:" from https://en.wikipedia.org/w/api.php?action=help&recursivesubmodules=1...

There are probably more likely to be cases of situation 2, spread out across various extensions too.

Is it worth the hassle of writing some sort of phpcs type "check" to find these things? A PHPCS rule where ApiBase::PARAM_TYPE has a value of an array, but no ApiBase::PARAM_HELP_MSG_PER_VALUE shouldn't be too difficult to write, I'd guess. And like all rules, they can be disabled by default (if they don't pass), and incrementally enabled as things are fixed.

I wonder if this becomes an Epic at this point.

Change 701595 had a related patch set uploaded (by Reedy; author: Reedy):

[mediawiki/core@master] Api: Convert errorformat to use PARAM_HELP_MSG_PER_VALUE

https://gerrit.wikimedia.org/r/701595

Change 701598 had a related patch set uploaded (by Reedy; author: Reedy):

[mediawiki/core@master] Api: Convert php and json formatversion to use PARAM_HELP_MSG_PER_VALUE

https://gerrit.wikimedia.org/r/701598

Jdforrester-WMF renamed this task from Make better use of PARAM_HELP_MSG_PER_VALUE to Make better use of PARAM_HELP_MSG_PER_VALUE across all Wikimedia-deployed MediaWiki code.Jul 13 2021, 1:42 PM
Jdforrester-WMF added a project: Epic.

Change 701595 merged by jenkins-bot:

[mediawiki/core@master] Api: Convert errorformat to use PARAM_HELP_MSG_PER_VALUE

https://gerrit.wikimedia.org/r/701595

Change 701598 merged by jenkins-bot:

[mediawiki/core@master] Api: Convert php and json formatversion to use PARAM_HELP_MSG_PER_VALUE

https://gerrit.wikimedia.org/r/701598