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:
- 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.",
- 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
Codesearch for 1.: https://codesearch.wmcloud.org/search/?q=-param-\w+": "[^"]*\\n;&files=en\.json