Page MenuHomePhabricator

Make better use of PARAM_HELP_MSG_PER_VALUE across all Wikimedia-deployed MediaWiki code
Closed, ResolvedPublic

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

Codesearch for 1.: https://codesearch.wmcloud.org/search/?q=-param-%5Cw%2B%22%3A+%22%5B%5E%22%5D*%5C%5Cn%3B&files=en%5C.json

Details

SubjectRepoBranchLines +/-
mediawiki/coreREL1_39+9 -1
mediawiki/coreREL1_39+10 -1
mediawiki/coreREL1_39+9 -2
mediawiki/coreREL1_39+32 -3
mediawiki/coreREL1_39+49 -1
mediawiki/coreREL1_39+21 -4
mediawiki/coreREL1_40+9 -1
mediawiki/coreREL1_40+10 -1
mediawiki/coreREL1_40+32 -3
mediawiki/coreREL1_40+9 -2
mediawiki/coreREL1_40+21 -4
mediawiki/coreREL1_40+49 -1
mediawiki/extensions/Wikibasemaster+7 -1
mediawiki/coremaster+10 -1
mediawiki/coremaster+21 -4
mediawiki/extensions/Gadgetsmaster+16 -2
mediawiki/coremaster+32 -3
mediawiki/extensions/PageImagesmaster+12 -4
mediawiki/extensions/ProofreadPagemaster+8 -3
mediawiki/extensions/SiteMatrixmaster+8 -3
mediawiki/extensions/Translatemaster+48 -7
mediawiki/coremaster+9 -2
mediawiki/coremaster+9 -1
mediawiki/extensions/GlobalUsagemaster+8 -1
mediawiki/extensions/TextExtractsmaster+8 -1
mediawiki/extensions/CentralAuthmaster+33 -7
mediawiki/extensions/JsonConfigmaster+10 -3
mediawiki/extensions/CheckUsermaster+19 -3
mediawiki/coremaster+49 -1
mediawiki/coremaster+18 -6
mediawiki/coremaster+14 -1
Show related patches Customize query in gerrit

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

Change 945881 had a related patch set uploaded (by Umherirrender; author: Umherirrender):

[mediawiki/extensions/CheckUser@master] i18n: Split apihelp for parameter list=checkuser&request=

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

Change 945882 had a related patch set uploaded (by Umherirrender; author: Umherirrender):

[mediawiki/extensions/GlobalUsage@master] i18n: Split apihelp for parameter prop=globalusage&guprop=

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

Change 945884 had a related patch set uploaded (by Umherirrender; author: Umherirrender):

[mediawiki/extensions/Gadgets@master] i18n: Split apihelp for parameter list=gadgets/gadgetcategories prop=

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

Change 945886 had a related patch set uploaded (by Umherirrender; author: Umherirrender):

[mediawiki/extensions/ProofreadPage@master] i18n: Split apihelp for parameter meta=proofreadinfo&prpiprop=

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

Change 945887 had a related patch set uploaded (by Umherirrender; author: Umherirrender):

[mediawiki/extensions/PageImages@master] i18n: Split apihelp for parameter prop=pageimages&piprop=

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

Change 945888 had a related patch set uploaded (by Umherirrender; author: Umherirrender):

[mediawiki/extensions/SiteMatrix@master] i18n: Split apihelp for parameter action=sitematrix&smtype=

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

Change 945889 had a related patch set uploaded (by Umherirrender; author: Umherirrender):

[mediawiki/extensions/TextExtracts@master] i18n: Split apihelp for parameter prop=extracts&exsectionformat=

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

Change 945890 had a related patch set uploaded (by Umherirrender; author: Umherirrender):

[mediawiki/extensions/CentralAuth@master] i18n: Split apihelp for parameter globalallusers/userinfo/wikisets prop

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

Change 945891 had a related patch set uploaded (by Umherirrender; author: Umherirrender):

[mediawiki/extensions/JsonConfig@master] i18n: Split apihelp for parameter action=jsonconfig&command=

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

Change 945892 had a related patch set uploaded (by Umherirrender; author: Umherirrender):

[mediawiki/extensions/Wikibase@master] i18n: Split apihelp for parameter meta=wikibase&wbprop=

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

Change 945893 had a related patch set uploaded (by Umherirrender; author: Umherirrender):

[mediawiki/extensions/Translate@master] i18n: Split apihelp for parameter messagecollection/messagegroups prop

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

Change 945902 had a related patch set uploaded (by Umherirrender; author: Umherirrender):

[mediawiki/core@master] i18n: Split apihelp for parameter action=managetags&operation=

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

Change 945903 had a related patch set uploaded (by Umherirrender; author: Umherirrender):

[mediawiki/core@master] i18n: Split apihelp for parameter action=opensearch&redirects=

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

Change 945904 had a related patch set uploaded (by Umherirrender; author: Umherirrender):

[mediawiki/core@master] i18n: Split apihelp for parameter list=allpages&apprexpiry=

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

Change 945905 had a related patch set uploaded (by Umherirrender; author: Umherirrender):

[mediawiki/core@master] i18n: Split apihelp for parameter list=deletedrevs&drprop=

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

Change 945906 had a related patch set uploaded (by Umherirrender; author: Umherirrender):

[mediawiki/core@master] i18n: Split apihelp for parameter prop=globalusage&guprop=

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

Change 945907 had a related patch set uploaded (by Umherirrender; author: Umherirrender):

[mediawiki/core@master] i18n: Split apihelp for standard dir parameter

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

Change 945907 merged by jenkins-bot:

[mediawiki/core@master] i18n: Split apihelp for standard dir parameter

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

Change 945904 merged by jenkins-bot:

[mediawiki/core@master] i18n: Split apihelp for parameter list=allpages&apprexpiry=

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

Change 945903 merged by jenkins-bot:

[mediawiki/core@master] i18n: Split apihelp for parameter action=opensearch&redirects=

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

Change 945881 merged by jenkins-bot:

[mediawiki/extensions/CheckUser@master] i18n: Split apihelp for parameter list=checkuser&curequest= and dir=

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

Change 945891 merged by jenkins-bot:

[mediawiki/extensions/JsonConfig@master] i18n: Split apihelp for parameter action=jsonconfig&command=

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

Change 945890 merged by jenkins-bot:

[mediawiki/extensions/CentralAuth@master] i18n: Split apihelp for parameter globalallusers/userinfo/wikisets prop

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

Change 945889 merged by jenkins-bot:

[mediawiki/extensions/TextExtracts@master] i18n: Split apihelp for parameter prop=extracts&exsectionformat=

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

Change 945882 merged by jenkins-bot:

[mediawiki/extensions/GlobalUsage@master] i18n: Split apihelp for parameter prop=globalusage&guprop=

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

Change 945893 merged by jenkins-bot:

[mediawiki/extensions/Translate@master] i18n: Split apihelp for parameter messagecollection/messagegroups prop

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

Change 945905 merged by jenkins-bot:

[mediawiki/core@master] i18n: Split apihelp for parameter list=deletedrevs&drprop=

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

Change 945902 merged by jenkins-bot:

[mediawiki/core@master] i18n: Split apihelp for parameter action=managetags&operation=

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

Change 945888 merged by jenkins-bot:

[mediawiki/extensions/SiteMatrix@master] i18n: Split apihelp for parameter action=sitematrix&smtype=

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

Change 945887 merged by jenkins-bot:

[mediawiki/extensions/PageImages@master] i18n: Split apihelp for parameter prop=pageimages&piprop=

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

Change 945886 merged by jenkins-bot:

[mediawiki/extensions/ProofreadPage@master] i18n: Split apihelp for parameter meta=proofreadinfo&prpiprop=

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

Change 945906 merged by jenkins-bot:

[mediawiki/core@master] i18n: Split apihelp for redirects/linkshere/transcludedin/fileusage show

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

Change 945884 merged by jenkins-bot:

[mediawiki/extensions/Gadgets@master] i18n: Split apihelp for parameter list=gadgets/gadgetcategories prop=

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

Change 945892 merged by jenkins-bot:

[mediawiki/extensions/Wikibase@master] i18n: Split apihelp for parameter meta=wikibase&wbprop=

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

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

[mediawiki/core@REL1_40] i18n: Split apihelp for standard dir parameter

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

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

[mediawiki/core@REL1_40] i18n: Split apihelp for redirects/linkshere/transcludedin/fileusage show

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

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

[mediawiki/core@REL1_40] i18n: Split apihelp for parameter list=deletedrevs&drprop=

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

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

[mediawiki/core@REL1_40] i18n: Split apihelp for parameter list=allpages&apprexpiry=

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

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

[mediawiki/core@REL1_40] i18n: Split apihelp for parameter action=opensearch&redirects=

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

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

[mediawiki/core@REL1_40] i18n: Split apihelp for parameter action=managetags&operation=

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

Change 959263 merged by jenkins-bot:

[mediawiki/core@REL1_40] i18n: Split apihelp for standard dir parameter

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

Change 959264 merged by jenkins-bot:

[mediawiki/core@REL1_40] i18n: Split apihelp for redirects/linkshere/transcludedin/fileusage show

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

Change 959265 merged by jenkins-bot:

[mediawiki/core@REL1_40] i18n: Split apihelp for parameter list=deletedrevs&drprop=

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

Change 959266 merged by jenkins-bot:

[mediawiki/core@REL1_40] i18n: Split apihelp for parameter list=allpages&apprexpiry=

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

Change 959267 merged by jenkins-bot:

[mediawiki/core@REL1_40] i18n: Split apihelp for parameter action=opensearch&redirects=

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

Change 959268 merged by jenkins-bot:

[mediawiki/core@REL1_40] i18n: Split apihelp for parameter action=managetags&operation=

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

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

[mediawiki/core@REL1_39] i18n: Split apihelp for standard dir parameter

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

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

[mediawiki/core@REL1_39] i18n: Split apihelp for redirects/linkshere/transcludedin/fileusage show

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

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

[mediawiki/core@REL1_39] i18n: Split apihelp for parameter list=deletedrevs&drprop=

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

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

[mediawiki/core@REL1_39] i18n: Split apihelp for parameter list=allpages&apprexpiry=

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

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

[mediawiki/core@REL1_39] i18n: Split apihelp for parameter action=opensearch&redirects=

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

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

[mediawiki/core@REL1_39] i18n: Split apihelp for parameter action=managetags&operation=

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

Change 959281 merged by jenkins-bot:

[mediawiki/core@REL1_39] i18n: Split apihelp for standard dir parameter

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

Change 959282 merged by jenkins-bot:

[mediawiki/core@REL1_39] i18n: Split apihelp for redirects/linkshere/transcludedin/fileusage show

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

Change 959283 merged by jenkins-bot:

[mediawiki/core@REL1_39] i18n: Split apihelp for parameter list=deletedrevs&drprop=

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

Change 959284 merged by jenkins-bot:

[mediawiki/core@REL1_39] i18n: Split apihelp for parameter list=allpages&apprexpiry=

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

Change 959285 merged by jenkins-bot:

[mediawiki/core@REL1_39] i18n: Split apihelp for parameter action=opensearch&redirects=

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

Change 959306 merged by jenkins-bot:

[mediawiki/core@REL1_39] i18n: Split apihelp for parameter action=managetags&operation=

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