Page MenuHomePhabricator
Create Task
Maniphest T284451

Allow better documentation of Api allowed parameters, where parameters are a list of specific values
Closed, InvalidPublic
Actions

Description

Noting this is probably pretty low priority in terms of engineering effort, but filing a task after mentioning in T283040: Aspect values are poorly documented in API help pages.

Taking, for example, the API "errorformat" parameter, it takes a value in a list of pre-defined strings

			'errorformat' => [
				ApiBase::PARAM_TYPE => [ 'plaintext', 'wikitext', 'html', 'raw', 'none', 'bc' ],
				ApiBase::PARAM_DFLT => 'bc',
			],

These are then documented in the API description for that parameter in one big text blob

	"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.",

Which results in something like

Screenshot 2021-06-07 at 14.38.14.png (1,760×574 px, 105 KB)

It would be "nice" if for these use cases, you could define something like apihelp-main-param-errorformat-value-plaintext, apihelp-main-param-errorformat-value-wikitext and be able to have that all displayed in the output, rather than reusing a bigger more overarching message.

Related Objects

Event Timeline

Reedy created this task.Jun 7 2021, 1:45 PM
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptJun 7 2021, 1:45 PM
DannyS712 subscribed.Jun 7 2021, 1:46 PM
Michael subscribed.Jun 21 2021, 9:37 AM
Michael added a comment.Jun 21 2021, 10:48 AM

I worked on the task that triggered this one and to me it seems the functionality suggested here already exists? See my patch: https://gerrit.wikimedia.org/r/c/mediawiki/extensions/Wikibase/+/700505/1

Maybe the functionality of ApiBase::PARAM_HELP_MSG_PER_VALUE => [] needs some better visibility? I only discovered it because it was already used for another parameter (prop) of this sam e API endpoint.

Reedy added a comment.Jun 21 2021, 11:00 AM

Curious. It has more usages than I expected (see at the bottom), and it's been around since MW 1.25... :)

It would indeeed look like you're right. So maybe this task needs repurposing (or probably to be cleaner, close this one, and file one or two new ones for the use cases) to update/split various messages (like apihelp-main-param-errorformat) into using ApiBase::PARAM_HELP_MSG_PER_VALUE instead, which in turn probably helps with better visibility.

I'm guessing there's 2 cases here... One, where there's multiple values mashed into the message description, and should be split out:

"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.",

And the second is basically cases of things like T283040: Aspect values are poorly documented in API help pages, where the values aren't currently documented at all in the output.

I do note the ApiBase::PARAM_HELP_MSG_PER_VALUE => [] syntax is a little weird, and easier to miss what it's doing (ie where you saw it), but that's not really a major issue if you can more easily find the examples showing what you want.

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

Class constant
    PARAM_HELP_MSG_PER_VALUE
Usages in Project and Libraries  (84 usages found)
    core  (59 usages found)
        includes  (52 usages found)
            api  (52 usages found)
                Validator  (7 usages found)
                    ApiParamValidator.php  (7 usages found)
                        202 ApiBase::PARAM_HELP_MSG_INFO, ApiBase::PARAM_HELP_MSG_PER_VALUE, ApiBase::PARAM_TEMPLATE_VARS,
                        255 if ( isset( $settings[ApiBase::PARAM_HELP_MSG_PER_VALUE] ) ) {
                        256 if ( !is_array( $settings[ApiBase::PARAM_HELP_MSG_PER_VALUE] ) ) {
                        257 $ret['issues'][ApiBase::PARAM_HELP_MSG_PER_VALUE] = 'PARAM_HELP_MSG_PER_VALUE must be an array,'
                        258 . ' got ' . gettype( $settings[ApiBase::PARAM_HELP_MSG_PER_VALUE] );
                        260 $ret['issues'][ApiBase::PARAM_HELP_MSG_PER_VALUE] = 'PARAM_HELP_MSG_PER_VALUE can only be used '
                        264 foreach ( $settings[ApiBase::PARAM_HELP_MSG_PER_VALUE] as $k => $v ) {
                ApiBase.php  (3 usages found)
                    1813 } elseif ( isset( $settings[self::PARAM_HELP_MSG_PER_VALUE] ) ) {
                    1814 if ( !is_array( $settings[self::PARAM_HELP_MSG_PER_VALUE] ) ) {
                    1824 $valueMsgs = $settings[self::PARAM_HELP_MSG_PER_VALUE];
                ApiComparePages.php  (1 usage found)
                    728 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiExpandTemplates.php  (1 usage found)
                    231 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiFeedWatchlist.php  (3 usages found)
                    277 isset( $p[ApiBase::PARAM_HELP_MSG_PER_VALUE] )
                    280 if ( !isset( $p[ApiBase::PARAM_HELP_MSG_PER_VALUE][$v] ) ) {
                    281 $p[ApiBase::PARAM_HELP_MSG_PER_VALUE][$v] = "apihelp-query+watchlist-paramvalue-$from-$v";
                ApiParse.php  (1 usage found)
                    955 ApiBase::PARAM_HELP_MSG_PER_VALUE => [
                ApiQueryAllCategories.php  (1 usage found)
                    188 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryAllImages.php  (1 usage found)
                    365 ApiBase::PARAM_HELP_MSG_PER_VALUE =>
                ApiQueryAllLinks.php  (1 usage found)
                    278 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryAllUsers.php  (1 usage found)
                    368 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryBacklinksprop.php  (1 usage found)
                    380 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryBlocks.php  (1 usage found)
                    425 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryCategories.php  (1 usage found)
                    193 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryCategoryMembers.php  (1 usage found)
                    319 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryExtLinksUsage.php  (1 usage found)
                    218 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryFilearchive.php  (1 usage found)
                    281 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryFileRepoInfo.php  (1 usage found)
                    88 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryImageInfo.php  (1 usage found)
                    675 ApiBase::PARAM_HELP_MSG_PER_VALUE => static::getPropertyMessages(),
                ApiQueryInfo.php  (2 usages found)
                    1076 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                    1093 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryIWBacklinks.php  (1 usage found)
                    203 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryIWLinks.php  (1 usage found)
                    159 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryLangBacklinks.php  (1 usage found)
                    202 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryLangLinks.php  (1 usage found)
                    162 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryLanguageinfo.php  (1 usage found)
                    246 self::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryLogEvents.php  (1 usage found)
                    426 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryMyStashedFiles.php  (1 usage found)
                    123 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryPagesWithProp.php  (1 usage found)
                    151 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryProtectedTitles.php  (1 usage found)
                    240 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryRecentChanges.php  (1 usage found)
                    782 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryRevisionsBase.php  (1 usage found)
                    704 ApiBase::PARAM_HELP_MSG_PER_VALUE => [
                ApiQuerySearch.php  (1 usage found)
                    384 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQuerySiteinfo.php  (1 usage found)
                    957 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryStashImageInfo.php  (1 usage found)
                    121 ApiBase::PARAM_HELP_MSG_PER_VALUE => self::getPropertyMessages()
                ApiQueryTags.php  (1 usage found)
                    150 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryUserContribs.php  (1 usage found)
                    647 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryUserInfo.php  (1 usage found)
                    377 ApiBase::PARAM_HELP_MSG_PER_VALUE => [
                ApiQueryUsers.php  (1 usage found)
                    396 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryWatchlist.php  (2 usages found)
                    497 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                    535 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiQueryWatchlistRaw.php  (1 usage found)
                    179 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                SearchApi.php  (1 usage found)
                    132 ApiBase::PARAM_HELP_MSG_PER_VALUE => $helpMessages,
        tests  (7 usages found)
            phpunit  (7 usages found)
                includes  (7 usages found)
                    api  (7 usages found)
                        Validator  (7 usages found)
                            ApiParamValidatorTest.php  (7 usages found)
                                179 ApiBase::PARAM_HELP_MSG_INFO, ApiBase::PARAM_HELP_MSG_PER_VALUE, ApiBase::PARAM_TEMPLATE_VARS,
                                226 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                                247 ApiBase::PARAM_HELP_MSG_PER_VALUE => true,
                                258 ApiBase::PARAM_HELP_MSG_PER_VALUE => 'PARAM_HELP_MSG_PER_VALUE must be an array, got boolean',
                                361 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                                367 ApiBase::PARAM_HELP_MSG_PER_VALUE
                                377 ApiBase::PARAM_HELP_MSG_PER_VALUE => [
    extensions  (25 usages found)
        BlueSpiceFoundation  (1 usage found)
            includes  (1 usage found)
                api  (1 usage found)
                    BSApiTasksBase.php  (1 usage found)
                        354 ApiBase::PARAM_HELP_MSG_PER_VALUE => $this->makeTaskHelpMessages()
        DiscussionTools  (2 usages found)
            includes  (2 usages found)
                ApiDiscussionTools.php  (1 usage found)
                    93 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                ApiDiscussionToolsEdit.php  (1 usage found)
                    256 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
        Echo  (1 usage found)
            includes  (1 usage found)
                api  (1 usage found)
                    ApiEchoNotifications.php  (1 usage found)
                        568 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
        GeoData  (4 usages found)
            includes  (4 usages found)
                Api  (4 usages found)
                    QueryCoordinates.php  (2 usages found)
                        170 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                        175 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                    QueryGeoSearch.php  (2 usages found)
                        207 ApiBase::PARAM_HELP_MSG_PER_VALUE => array_map( static function ( $i ) use ( $propTypes ) {
                        214 ApiBase::PARAM_HELP_MSG_PER_VALUE => array_map( static function ( $i ) use ( $primaryTypes ) {
        GlobalPreferences  (1 usage found)
            includes  (1 usage found)
                ApiQueryGlobalPreferences.php  (1 usage found)
                    95 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
        GrowthExperiments  (3 usages found)
            includes  (3 usages found)
                Api  (3 usages found)
                    ApiHelpPanelPostQuestion.php  (1 usage found)
                        140 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                    ApiQueryGrowthTasks.php  (2 usages found)
                        156 ApiBase::PARAM_HELP_MSG_PER_VALUE => array_map( function ( TaskType $taskType ) {
                        164 ApiBase::PARAM_HELP_MSG_PER_VALUE => array_map( function ( Topic $topic ) {
        MachineVision  (2 usages found)
            src  (2 usages found)
                Api  (2 usages found)
                    ApiQueryImageLabels.php  (1 usage found)
                        129 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                    ApiReviewImageLabels.php  (1 usage found)
                        307 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
        PageViewInfo  (1 usage found)
            includes  (1 usage found)
                Hooks.php  (1 usage found)
                    152 ApiBase::PARAM_HELP_MSG_PER_VALUE => array_map( static function ( $metric ) {
        ReadingLists  (1 usage found)
            src  (1 usage found)
                Api  (1 usage found)
                    ApiQueryTrait.php  (1 usage found)
                        133 self::PARAM_HELP_MSG_PER_VALUE => [],
        SecurePoll  (1 usage found)
            includes  (1 usage found)
                Api  (1 usage found)
                    ApiStrikeVote.php  (1 usage found)
                        141 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
        Wikibase  (7 usages found)
            client  (5 usages found)
                includes  (5 usages found)
                    Api  (5 usages found)
                        ApiFormatReference.php  (2 usages found)
                            104 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                            111 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                        ApiListEntityUsage.php  (1 usage found)
                            262 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                        ApiPropsEntityUsage.php  (1 usage found)
                            180 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
                        Description.php  (1 usage found)
                            152 self::PARAM_HELP_MSG_PER_VALUE => [],
            repo  (2 usages found)
                includes  (2 usages found)
                    Api  (2 usages found)
                        MetaContentLanguages.php  (2 usages found)
                            135 self::PARAM_HELP_MSG_PER_VALUE => [],
                            145 self::PARAM_HELP_MSG_PER_VALUE => [],
        WikibaseQualityConstraints  (1 usage found)
            src  (1 usage found)
                Api  (1 usage found)
                    CheckConstraints.php  (1 usage found)
                        263 ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
Reedy closed this task as Invalid.Jun 25 2021, 1:08 PM

I'm going to mark this one invalid, and create a fork task or two to improve the individual cases

Reedy mentioned this in T285545: Make better use of PARAM_HELP_MSG_PER_VALUE across all Wikimedia-deployed MediaWiki code.Jun 25 2021, 1:16 PM
Reedy mentioned this in T283040: Aspect values are poorly documented in API help pages.
Content licensed under Creative Commons Attribution-ShareAlike (CC BY-SA) 4.0 unless otherwise noted; code licensed under GNU General Public License (GPL) 2.0 or later and other open source licenses. By using this site, you agree to the Terms of Use, Privacy Policy, and Code of Conduct. · Wikimedia Foundation · Privacy Policy · Code of Conduct · Terms of Use · Disclaimer · CC-BY-SA · GPL · Credits