From: Brad Jorsch Date: Wed, 10 Oct 2018 17:14:13 +0000 (-0400) Subject: Remove use of old API doc methods X-Git-Tag: 1.34.0-rc.0~3610^2 X-Git-Url: http://git.cyclocoop.org/?a=commitdiff_plain;h=afe9a0fa5bd8fdcc9f2a9403f366e24f46fd64d1;p=lhc%2Fweb%2Fwiklou.git Remove use of old API doc methods The following deprecated methods, intended for overriding by extensions, are no longer called and are hard deprecated. * ApiBase::getDescription() (deprecated in 1.25) * ApiBase::getParamDescription() (deprecated in 1.25) * ApiBase::getExamples() (deprecated in 1.25) * ApiBase::getDescriptionMessage() (deprecated in 1.30) Also, the 'APIGetDescription' and 'APIGetParamDescription' hooks have been removed, as their only use was to allow extensions to override values returned by getDescription() and getParamDescription(), respectively. Change-Id: I486c4ccab4eca6a85cb17c30dbb2439876123ba1 --- diff --git a/RELEASE-NOTES-1.33 b/RELEASE-NOTES-1.33 index 42fa12ac45..e7ada4cc95 100644 --- a/RELEASE-NOTES-1.33 +++ b/RELEASE-NOTES-1.33 @@ -41,6 +41,16 @@ production. * … === Action API internal changes in 1.33 === +* A number of deprecated methods for API documentation, intended for overriding + by extensions, are no longer called by MediaWiki, and will emit deprecation + notices if your extension attempts to use them: + * ApiBase::getDescription() (deprecated in 1.25) + * ApiBase::getParamDescription() (deprecated in 1.25) + * ApiBase::getExamples() (deprecated in 1.25) + * ApiBase::getDescriptionMessage() (deprecated in 1.30) + Additionally, the 'APIGetDescription' and 'APIGetParamDescription' hooks have + been removed, as their only use was to let extensions override values returned + by getDescription() and getParamDescription(), respectively. * … === Languages updated in 1.33 === @@ -69,6 +79,16 @@ because of Phabricator reports. * ParserOptions defaults 'tidy' to true now, since the untidy modes of the parser are being deprecated and ParserOptions::getCanonicalOverrides() has always been true at any rate. +* A number of deprecated methods for API documentation, intended for overriding + by extensions, are no longer called by MediaWiki, and will emit deprecation + notices if your extension attempts to use them: + * ApiBase::getDescription() (deprecated in 1.25) + * ApiBase::getParamDescription() (deprecated in 1.25) + * ApiBase::getExamples() (deprecated in 1.25) + * ApiBase::getDescriptionMessage() (deprecated in 1.30) + Additionally, the 'APIGetDescription' and 'APIGetParamDescription' hooks have + been removed, as their only use was to let extensions override values returned + by getDescription() and getParamDescription(), respectively. * … === Deprecations in 1.33 === diff --git a/docs/hooks.txt b/docs/hooks.txt index f9ae150aab..5afd6fbf39 100644 --- a/docs/hooks.txt +++ b/docs/hooks.txt @@ -415,21 +415,10 @@ $format: API format code for $text. &$params: Array of parameters $flags: int zero or OR-ed flags like ApiBase::GET_VALUES_FOR_HELP -'APIGetDescription': DEPRECATED since 1.25! Use APIGetDescriptionMessages -instead. Use this hook to modify a module's description. -&$module: ApiBase Module object -&$desc: String description, or array of description strings - 'APIGetDescriptionMessages': Use this hook to modify a module's help message. $module: ApiBase Module object &$msg: Array of Message objects -'APIGetParamDescription': DEPRECATED since 1.25! Use -APIGetParamDescriptionMessages instead. -Use this hook to modify a module's parameter descriptions. -&$module: ApiBase Module object -&$desc: Array of parameter descriptions - 'APIGetParamDescriptionMessages': Use this hook to modify a module's parameter descriptions. $module: ApiBase Module object diff --git a/includes/api/ApiBase.php b/includes/api/ApiBase.php index 1ca54c1c14..c66e5d52bb 100644 --- a/includes/api/ApiBase.php +++ b/includes/api/ApiBase.php @@ -348,45 +348,7 @@ abstract class ApiBase extends ContextSource { * @return array */ protected function getExamplesMessages() { - // Fall back to old non-localised method - $ret = []; - - $examples = $this->getExamples(); - if ( $examples ) { - if ( !is_array( $examples ) ) { - $examples = [ $examples ]; - } elseif ( $examples && ( count( $examples ) & 1 ) == 0 && - array_keys( $examples ) === range( 0, count( $examples ) - 1 ) && - !preg_match( '/^\s*api\.php\?/', $examples[0] ) - ) { - // Fix up the ugly "even numbered elements are description, odd - // numbered elemts are the link" format (see doc for self::getExamples) - $tmp = []; - $examplesCount = count( $examples ); - for ( $i = 0; $i < $examplesCount; $i += 2 ) { - $tmp[$examples[$i + 1]] = $examples[$i]; - } - $examples = $tmp; - } - - foreach ( $examples as $k => $v ) { - if ( is_numeric( $k ) ) { - $qs = $v; - $msg = ''; - } else { - $qs = $k; - $msg = self::escapeWikiText( $v ); - if ( is_array( $msg ) ) { - $msg = implode( ' ', $msg ); - } - } - - $qs = preg_replace( '/^\s*api\.php\?/', '', $qs ); - $ret[$qs] = $this->msg( 'api-help-fallback-example', [ $msg ] ); - } - } - - return $ret; + return []; } /** @@ -1784,25 +1746,6 @@ abstract class ApiBase extends ContextSource { return $user; } - /** - * A subset of wfEscapeWikiText for BC texts - * - * @since 1.25 - * @param string|array $v - * @return string|array - */ - private static function escapeWikiText( $v ) { - if ( is_array( $v ) ) { - return array_map( 'self::escapeWikiText', $v ); - } else { - return strtr( $v, [ - '__' => '__', '{' => '{', '}' => '}', - '[[Category:' => '[[:Category:', - '[[File:' => '[[:File:', '[[Image:' => '[[:Image:', - ] ); - } - } - /** * Create a Message from a string or array * @@ -2230,10 +2173,6 @@ abstract class ApiBase extends ContextSource { /** * Get final module summary * - * Ideally this will just be the getSummaryMessage(). However, for - * backwards compatibility, if that message does not exist then the first - * line of wikitext from the description message will be used instead. - * * @since 1.30 * @return Message */ @@ -2243,17 +2182,6 @@ abstract class ApiBase extends ContextSource { $this->getModuleName(), $this->getModulePath(), ] ); - if ( !$msg->exists() ) { - wfDeprecated( 'API help "description" messages', '1.30' ); - $msg = self::makeMessage( $this->getDescriptionMessage(), $this->getContext(), [ - $this->getModulePrefix(), - $this->getModuleName(), - $this->getModulePath(), - ] ); - $msg = self::makeMessage( 'rawmessage', $this->getContext(), [ - preg_replace( '/\n.*/s', '', $msg->text() ) - ] ); - } return $msg; } @@ -2265,18 +2193,6 @@ abstract class ApiBase extends ContextSource { * @return Message[] */ public function getFinalDescription() { - $desc = $this->getDescription(); - - // Avoid PHP 7.1 warning of passing $this by reference - $apiModule = $this; - Hooks::run( 'APIGetDescription', [ &$apiModule, &$desc ], '1.25' ); - $desc = self::escapeWikiText( $desc ); - if ( is_array( $desc ) ) { - $desc = implode( "\n", $desc ); - } else { - $desc = (string)$desc; - } - $summary = self::makeMessage( $this->getSummaryMessage(), $this->getContext(), [ $this->getModulePrefix(), $this->getModuleName(), @@ -2290,20 +2206,7 @@ abstract class ApiBase extends ContextSource { ] ); - if ( $summary->exists() ) { - $msgs = [ $summary, $extendedDescription ]; - } else { - wfDeprecated( 'API help "description" messages', '1.30' ); - $description = self::makeMessage( $this->getDescriptionMessage(), $this->getContext(), [ - $this->getModulePrefix(), - $this->getModuleName(), - $this->getModulePath(), - ] ); - if ( !$description->exists() ) { - $description = $this->msg( 'api-help-fallback-description', $desc ); - } - $msgs = [ $description ]; - } + $msgs = [ $summary, $extendedDescription ]; Hooks::run( 'APIGetDescriptionMessages', [ $this, &$msgs ] ); @@ -2355,17 +2258,6 @@ abstract class ApiBase extends ContextSource { $name = $this->getModuleName(); $path = $this->getModulePath(); - $desc = $this->getParamDescription(); - - // Avoid PHP 7.1 warning of passing $this by reference - $apiModule = $this; - Hooks::run( 'APIGetParamDescription', [ &$apiModule, &$desc ], '1.25' ); - - if ( !$desc ) { - $desc = []; - } - $desc = self::escapeWikiText( $desc ); - $params = $this->getFinalParams( self::GET_VALUES_FOR_HELP ); $msgs = []; foreach ( $params as $param => $settings ) { @@ -2373,25 +2265,10 @@ abstract class ApiBase extends ContextSource { $settings = []; } - $d = $desc[$param] ?? ''; - if ( is_array( $d ) ) { - // Special handling for prop parameters - $d = array_map( function ( $line ) { - if ( preg_match( '/^\s+(\S+)\s+-\s+(.+)$/', $line, $m ) ) { - $line = "\n;{$m[1]}:{$m[2]}"; - } - return $line; - }, $d ); - $d = implode( ' ', $d ); - } - if ( isset( $settings[self::PARAM_HELP_MSG] ) ) { $msg = $settings[self::PARAM_HELP_MSG]; } else { $msg = $this->msg( "apihelp-{$path}-param-{$param}" ); - if ( !$msg->exists() ) { - $msg = $this->msg( 'api-help-fallback-parameter', $d ); - } } $msg = self::makeMessage( $msg, $this->getContext(), [ $prefix, $param, $name, $path ] ); @@ -2654,6 +2531,7 @@ abstract class ApiBase extends ContextSource { * @return Message|string|array|false */ protected function getDescription() { + wfDeprecated( __METHOD__, '1.25' ); return false; } @@ -2670,6 +2548,7 @@ abstract class ApiBase extends ContextSource { * @return array|bool False on no parameter descriptions */ protected function getParamDescription() { + wfDeprecated( __METHOD__, '1.25' ); return []; } @@ -2690,6 +2569,7 @@ abstract class ApiBase extends ContextSource { * @return bool|string|array */ protected function getExamples() { + wfDeprecated( __METHOD__, '1.25' ); return false; } @@ -2702,6 +2582,7 @@ abstract class ApiBase extends ContextSource { * @return string|array|Message */ protected function getDescriptionMessage() { + wfDeprecated( __METHOD__, '1.30' ); return [ [ "apihelp-{$this->getModulePath()}-description", "apihelp-{$this->getModulePath()}-summary", diff --git a/includes/api/ApiDisabled.php b/includes/api/ApiDisabled.php index 32111894b8..5369768d45 100644 --- a/includes/api/ApiDisabled.php +++ b/includes/api/ApiDisabled.php @@ -40,10 +40,6 @@ class ApiDisabled extends ApiBase { return false; } - protected function getDescriptionMessage() { - return 'apihelp-disabled-summary'; - } - protected function getSummaryMessage() { return 'apihelp-disabled-summary'; } diff --git a/includes/api/ApiQueryDisabled.php b/includes/api/ApiQueryDisabled.php index 86100077a2..7f029546df 100644 --- a/includes/api/ApiQueryDisabled.php +++ b/includes/api/ApiQueryDisabled.php @@ -40,10 +40,6 @@ class ApiQueryDisabled extends ApiQueryBase { return []; } - public function getDescriptionMessage() { - return 'apihelp-query+disabled-summary'; - } - public function getSummaryMessage() { return 'apihelp-query+disabled-summary'; } diff --git a/includes/api/i18n/en.json b/includes/api/i18n/en.json index 588dbef1ed..83bb6e65d5 100644 --- a/includes/api/i18n/en.json +++ b/includes/api/i18n/en.json @@ -1605,9 +1605,6 @@ "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", "api-help-flags": "", "api-help-flag-deprecated": "This module is deprecated.", "api-help-flag-internal": "This module is internal or unstable. Its operation may change without notice.", diff --git a/includes/api/i18n/qqq.json b/includes/api/i18n/qqq.json index 4f68de09f9..83427bafd8 100644 --- a/includes/api/i18n/qqq.json +++ b/includes/api/i18n/qqq.json @@ -1495,9 +1495,6 @@ "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}}", "api-help-flags": "{{ignored}} Label for the API help flags box\n\nParameters:\n* $1 - Number of flags to be displayed", "api-help-flag-deprecated": "Flag displayed for an API module that is deprecated", "api-help-flag-internal": "Flag displayed for an API module that is considered internal or unstable",