From d4392eaaeac81f7526855601fe59e9b3afff335e Mon Sep 17 00:00:00 2001 From: Brad Jorsch Date: Thu, 25 May 2017 17:31:59 -0400 Subject: [PATCH] API: Display message-per-value style help for submodule parameters The module's summary will be used as the description of the value. Since these are often very long lists, this also changes ApiSandbox to collapse
lists in parameter descriptions by default. Bug: T123930 Change-Id: I205b68a52a94cae4c1cdf7ec9fd3e8a04d565919 --- includes/api/ApiBase.php | 44 +++++++++++++++++- includes/api/ApiHelp.php | 45 +++++++++++++------ includes/api/ApiParamInfo.php | 19 ++++++++ includes/api/i18n/en.json | 1 + includes/api/i18n/qqq.json | 1 + resources/Resources.php | 1 + .../mediawiki.special.apisandbox.js | 14 ++++-- 7 files changed, 107 insertions(+), 18 deletions(-) diff --git a/includes/api/ApiBase.php b/includes/api/ApiBase.php index aa970f4476..3a9167f0d0 100644 --- a/includes/api/ApiBase.php +++ b/includes/api/ApiBase.php @@ -2241,7 +2241,49 @@ abstract class ApiBase extends ContextSource { } $msgs[$param] = [ $msg ]; - if ( isset( $settings[ApiBase::PARAM_HELP_MSG_PER_VALUE] ) ) { + if ( isset( $settings[ApiBase::PARAM_TYPE] ) && + $settings[ApiBase::PARAM_TYPE] === 'submodule' + ) { + if ( isset( $settings[ApiBase::PARAM_SUBMODULE_MAP] ) ) { + $map = $settings[ApiBase::PARAM_SUBMODULE_MAP]; + } else { + $prefix = $this->isMain() ? '' : ( $this->getModulePath() . '+' ); + $map = []; + foreach ( $this->getModuleManager()->getNames( $param ) as $submoduleName ) { + $map[$submoduleName] = $prefix . $submoduleName; + } + } + ksort( $map ); + $submodules = []; + $deprecatedSubmodules = []; + foreach ( $map as $v => $m ) { + $arr = &$submodules; + $isDeprecated = false; + $summary = null; + try { + $submod = $this->getModuleFromPath( $m ); + if ( $submod ) { + $summary = $submod->getFinalSummary(); + $isDeprecated = $submod->isDeprecated(); + if ( $isDeprecated ) { + $arr = &$deprecatedSubmodules; + } + } + } catch ( ApiUsageException $ex ) { + // Ignore + } + if ( $summary ) { + $key = $summary->getKey(); + $params = $summary->getParams(); + } else { + $key = 'api-help-undocumented-module'; + $params = [ $m ]; + } + $m = new ApiHelpParamValueMessage( "[[Special:ApiHelp/$m|$v]]", $key, $params, $isDeprecated ); + $arr[] = $m->setContext( $this->getContext() ); + } + $msgs[$param] = array_merge( $msgs[$param], $submodules, $deprecatedSubmodules ); + } elseif ( isset( $settings[ApiBase::PARAM_HELP_MSG_PER_VALUE] ) ) { if ( !is_array( $settings[ApiBase::PARAM_HELP_MSG_PER_VALUE] ) ) { self::dieDebug( __METHOD__, 'ApiBase::PARAM_HELP_MSG_PER_VALUE is not valid' ); diff --git a/includes/api/ApiHelp.php b/includes/api/ApiHelp.php index 192c039651..3fd29ae928 100644 --- a/includes/api/ApiHelp.php +++ b/includes/api/ApiHelp.php @@ -529,23 +529,42 @@ class ApiHelp extends ApiBase { switch ( $type ) { case 'submodule': $groups[] = $name; + if ( isset( $settings[ApiBase::PARAM_SUBMODULE_MAP] ) ) { $map = $settings[ApiBase::PARAM_SUBMODULE_MAP]; - ksort( $map ); - $submodules = []; - foreach ( $map as $v => $m ) { - $submodules[] = "[[Special:ApiHelp/{$m}|{$v}]]"; - } + $defaultAttrs = []; } else { - $submodules = $module->getModuleManager()->getNames( $name ); - sort( $submodules ); - $prefix = $module->isMain() - ? '' : ( $module->getModulePath() . '+' ); - $submodules = array_map( function ( $name ) use ( $prefix ) { - $text = Html::element( 'span', [ 'dir' => 'ltr', 'lang' => 'en' ], $name ); - return "[[Special:ApiHelp/{$prefix}{$name}|{$text}]]"; - }, $submodules ); + $prefix = $module->isMain() ? '' : ( $module->getModulePath() . '+' ); + $map = []; + foreach ( $module->getModuleManager()->getNames( $name ) as $submoduleName ) { + $map[$submoduleName] = $prefix . $submoduleName; + } + $defaultAttrs = [ 'dir' => 'ltr', 'lang' => 'en' ]; + } + ksort( $map ); + + $submodules = []; + $deprecatedSubmodules = []; + foreach ( $map as $v => $m ) { + $attrs = $defaultAttrs; + $arr = &$submodules; + try { + $submod = $module->getModuleFromPath( $m ); + if ( $submod ) { + if ( $submod->isDeprecated() ) { + $arr = &$deprecatedSubmodules; + $attrs['class'] = 'apihelp-deprecated-value'; + } + } + } catch ( ApiUsageException $ex ) { + // Ignore + } + if ( $attrs ) { + $v = Html::element( 'span', $attrs, $v ); + } + $arr[] = "[[Special:ApiHelp/{$m}|{$v}]]"; } + $submodules = array_merge( $submodules, $deprecatedSubmodules ); $count = count( $submodules ); $info[] = $context->msg( 'api-help-param-list' ) ->params( $multi ? 2 : 1 ) diff --git a/includes/api/ApiParamInfo.php b/includes/api/ApiParamInfo.php index 3be743d026..4ce0e9f108 100644 --- a/includes/api/ApiParamInfo.php +++ b/includes/api/ApiParamInfo.php @@ -401,6 +401,25 @@ class ApiParamInfo extends ApiBase { if ( isset( $settings[ApiBase::PARAM_SUBMODULE_PARAM_PREFIX] ) ) { $item['submoduleparamprefix'] = $settings[ApiBase::PARAM_SUBMODULE_PARAM_PREFIX]; } + + $deprecatedSubmodules = []; + foreach ( $item['submodules'] as $v => $submodulePath ) { + try { + $submod = $this->getModuleFromPath( $submodulePath ); + if ( $submod && $submod->isDeprecated() ) { + $deprecatedSubmodules[] = $v; + } + } catch ( ApiUsageException $ex ) { + // Ignore + } + } + if ( $deprecatedSubmodules ) { + $item['type'] = array_merge( + array_diff( $item['type'], $deprecatedSubmodules ), + $deprecatedSubmodules + ); + $item['deprecatedvalues'] = $deprecatedSubmodules; + } } elseif ( $settings[ApiBase::PARAM_TYPE] === 'tags' ) { $item['type'] = ChangeTags::listExplicitlyDefinedTags(); } else { diff --git a/includes/api/i18n/en.json b/includes/api/i18n/en.json index 2a4dc0bf29..9ce10b9870 100644 --- a/includes/api/i18n/en.json +++ b/includes/api/i18n/en.json @@ -1555,6 +1555,7 @@ "api-help-title": "MediaWiki API help", "api-help-lead": "This is an auto-generated MediaWiki API documentation page.\n\nDocumentation and examples: https://www.mediawiki.org/wiki/API", "api-help-main-header": "Main module", + "api-help-undocumented-module": "No documentation for module $1.", "api-help-fallback-description": "$1", "api-help-fallback-parameter": "$1", "api-help-fallback-example": "$1", diff --git a/includes/api/i18n/qqq.json b/includes/api/i18n/qqq.json index 9bcfdb021d..bde0707814 100644 --- a/includes/api/i18n/qqq.json +++ b/includes/api/i18n/qqq.json @@ -1446,6 +1446,7 @@ "api-help-title": "Page title for the auto-generated help output", "api-help-lead": "Text displayed at the top of the API help page", "api-help-main-header": "Text for the header of the main module", + "api-help-undocumented-module": "Text displayed for the summary of a submodule parameter when the module can't be loaded.\n\nParameters:\n* $1 - The module path.", "api-help-fallback-description": "{{notranslate}}", "api-help-fallback-parameter": "{{notranslate}}", "api-help-fallback-example": "{{notranslate}}", diff --git a/resources/Resources.php b/resources/Resources.php index 864f93eabe..149bb0d1c6 100644 --- a/resources/Resources.php +++ b/resources/Resources.php @@ -1886,6 +1886,7 @@ return [ 'oojs-ui.styles.icons-interactions', 'oojs-ui.styles.icons-moderation', 'mediawiki.widgets.datetime', + 'jquery.makeCollapsible', ], 'messages' => [ 'apisandbox-intro', diff --git a/resources/src/mediawiki.special/mediawiki.special.apisandbox.js b/resources/src/mediawiki.special/mediawiki.special.apisandbox.js index c32f9535a9..3bd3bc85d4 100644 --- a/resources/src/mediawiki.special/mediawiki.special.apisandbox.js +++ b/resources/src/mediawiki.special/mediawiki.special.apisandbox.js @@ -1506,10 +1506,16 @@ } descriptionContainer = $( '
' ); - descriptionContainer.append( $( '
', { - addClass: 'description', - append: Util.parseHTML( pi.parameters[ i ].description ) - } ) ); + + tmp = Util.parseHTML( pi.parameters[ i ].description ); + tmp.filter( 'dl' ).makeCollapsible( { + collapsed: true + } ).children( '.mw-collapsible-toggle' ).each( function () { + var $this = $( this ); + $this.parent().prev( 'p' ).append( $this ); + } ); + descriptionContainer.append( $( '
', { addClass: 'description', append: tmp } ) ); + if ( pi.parameters[ i ].info && pi.parameters[ i ].info.length ) { for ( j = 0; j < pi.parameters[ i ].info.length; j++ ) { descriptionContainer.append( $( '
', { -- 2.20.1