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 42fa12a..e7ada4c 100644 (file)
--- 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 f9ae150..5afd6fb 100644 (file)
--- 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 1ca54c1..c66e5d5 100644 (file)
--- 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, [
-                               '__' => '_&#95;', '{' => '&#123;', '}' => '&#125;',
-                               '[[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 3211189..5369768 100644 (file)
--- 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 8610007..7f02954 100644 (file)
--- 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 588dbef..83bb6e6 100644 (file)
--- 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": "<strong>This module is internal or unstable.</strong> Its operation may change without notice.",

diff --git a/includes/api/i18n/qqq.json b/includes/api/i18n/qqq.json
index 4f68de0..83427ba 100644 (file)
--- 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",