* …
=== 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 ===
* 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 ===
* @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 [];
}
/**
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
*
/**
* 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
*/
$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;
}
* @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(),
]
);
- 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 ] );
$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 ) {
$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 ] );
* @return Message|string|array|false
*/
protected function getDescription() {
+ wfDeprecated( __METHOD__, '1.25' );
return false;
}
* @return array|bool False on no parameter descriptions
*/
protected function getParamDescription() {
+ wfDeprecated( __METHOD__, '1.25' );
return [];
}
* @return bool|string|array
*/
protected function getExamples() {
+ wfDeprecated( __METHOD__, '1.25' );
return false;
}
* @return string|array|Message
*/
protected function getDescriptionMessage() {
+ wfDeprecated( __METHOD__, '1.30' );
return [ [
"apihelp-{$this->getModulePath()}-description",
"apihelp-{$this->getModulePath()}-summary",