diff --git a/includes/api/ApiBase.php b/includes/api/ApiBase.php index cdd35fa5f5e..875c77bc107 100644 --- a/includes/api/ApiBase.php +++ b/includes/api/ApiBase.php @@ -45,6 +45,8 @@ use Wikimedia\Rdbms\IDatabase; * * Self-documentation: code to allow the API to document its own state * + * @stable for subclassing + * * @ingroup API */ abstract class ApiBase extends ContextSource { @@ -202,6 +204,7 @@ abstract class ApiBase extends ContextSource { private $mModuleSource = false; /** + * @stable for calling * @param ApiMain $mainModule * @param string $moduleName Name of this module * @param string $modulePrefix Prefix to use for parameter names @@ -242,6 +245,7 @@ abstract class ApiBase extends ContextSource { /** * Get the module manager, or null if this module has no sub-modules * @since 1.21 + * @stable for overriding * @return ApiModuleManager */ public function getModuleManager() { @@ -255,6 +259,7 @@ abstract class ApiBase extends ContextSource { * @note Do not use this just because you don't want to support non-json * formats. This should be used only when there is a fundamental * requirement for a specific format. + * @stable for overriding * @return mixed Instance of a derived class of ApiFormatBase, or null */ public function getCustomPrinter() { @@ -270,6 +275,7 @@ abstract class ApiBase extends ContextSource { * Do not call this base class implementation when overriding this method. * * @since 1.25 + * @stable for overriding * @return array */ protected function getExamplesMessages() { @@ -279,6 +285,7 @@ abstract class ApiBase extends ContextSource { /** * Return links to more detailed help pages about the module. * @since 1.25, returning boolean false is deprecated + * @stable for overriding * @return string|array */ public function getHelpUrls() { @@ -295,6 +302,7 @@ abstract class ApiBase extends ContextSource { * in the overriding methods. Callers of this method can pass zero or * more OR-ed flags like GET_VALUES_FOR_HELP. * + * @stable for overriding * @return array */ protected function getAllowedParams( /* $flags = 0 */ ) { @@ -305,6 +313,7 @@ abstract class ApiBase extends ContextSource { /** * Indicates if this module needs maxlag to be checked + * @stable for overriding * @return bool */ public function shouldCheckMaxlag() { @@ -313,6 +322,7 @@ abstract class ApiBase extends ContextSource { /** * Indicates whether this module requires read rights + * @stable for overriding * @return bool */ public function isReadMode() { @@ -328,6 +338,7 @@ abstract class ApiBase extends ContextSource { * Additionally, requests that only need replica DBs can be efficiently routed to any * datacenter via the Promise-Non-Write-API-Action header. * + * @stable for overriding * @return bool */ public function isWriteMode() { @@ -336,6 +347,7 @@ abstract class ApiBase extends ContextSource { /** * Indicates whether this module must be called with a POST request + * @stable for overriding * @return bool */ public function mustBePosted() { @@ -345,6 +357,7 @@ abstract class ApiBase extends ContextSource { /** * Indicates whether this module is deprecated * @since 1.25 + * @stable for overriding * @return bool */ public function isDeprecated() { @@ -355,6 +368,7 @@ abstract class ApiBase extends ContextSource { * Indicates whether this module is "internal" * Internal API modules are not (yet) intended for 3rd party use and may be unstable. * @since 1.25 + * @stable for overriding * @return bool */ public function isInternal() { @@ -377,6 +391,7 @@ abstract class ApiBase extends ContextSource { * Returning true will generate errors indicating that the API module needs * updating. * + * @stable for overriding * @return string|false */ public function needsToken() { @@ -390,6 +405,7 @@ abstract class ApiBase extends ContextSource { * * @since 1.24 * @param array $params All supplied parameters for the module + * @stable for overriding * @return string|array|null */ protected function getWebUITokenSalt( array $params ) { @@ -400,6 +416,7 @@ abstract class ApiBase extends ContextSource { * Returns data for HTTP conditional request mechanisms. * * @since 1.26 + * @stable for overriding * @param string $condition Condition being queried: * - last-modified: Return a timestamp representing the maximum of the * last-modified dates for all resources involved in the request. See @@ -454,6 +471,7 @@ abstract class ApiBase extends ContextSource { /** * Get the parent of this module + * @stable for overriding * @since 1.25 * @return ApiBase|null */ @@ -555,6 +573,7 @@ abstract class ApiBase extends ContextSource { /** * Get the error formatter + * @stable for overriding * @return ApiErrorFormatter */ public function getErrorFormatter() { @@ -569,6 +588,7 @@ abstract class ApiBase extends ContextSource { /** * Gets a default replica DB connection object + * @stable for overriding * @return IDatabase */ protected function getDB() { @@ -655,6 +675,7 @@ abstract class ApiBase extends ContextSource { /** * Indicate if the module supports dynamically-determined parameters that * cannot be included in self::getAllowedParams(). + * @stable for overriding * @return string|array|Message|null Return null if the module does not * support additional dynamic parameters, otherwise return a message * describing them. @@ -1658,6 +1679,7 @@ abstract class ApiBase extends ContextSource { * list of modules. * * @since 1.30 + * @stable for overriding * @return string|array|Message */ protected function getSummaryMessage() { @@ -1671,6 +1693,7 @@ abstract class ApiBase extends ContextSource { * the summary. * * @since 1.30 + * @stable for overriding * @return string|array|Message */ protected function getExtendedDescription() { @@ -1684,6 +1707,7 @@ abstract class ApiBase extends ContextSource { * Get final module summary * * @since 1.30 + * @stable for overriding * @return Message */ public function getFinalSummary() { @@ -2018,6 +2042,7 @@ abstract class ApiBase extends ContextSource { * This exists mainly for ApiMain to add the Permissions and Credits * sections. Other modules probably don't need it. * + * @stable for overriding * @param string[] &$help Array of help data * @param array $options Options passed to ApiHelp::getHelp * @param array &$tocData If a TOC is being generated, this array has keys diff --git a/includes/api/ApiQueryBase.php b/includes/api/ApiQueryBase.php index f54d5b49aa7..0a6cc077973 100644 --- a/includes/api/ApiQueryBase.php +++ b/includes/api/ApiQueryBase.php @@ -30,6 +30,8 @@ use Wikimedia\Rdbms\SelectQueryBuilder; * It provides some common functionality such as constructing various SQL * queries. * + * @stable for subclassing + * * @ingroup API */ abstract class ApiQueryBase extends ApiBase { @@ -43,6 +45,7 @@ abstract class ApiQueryBase extends ApiBase { private $queryBuilder; /** + * @stable for calling * @param ApiQuery $queryModule * @param string $moduleName * @param string $paramPrefix @@ -67,6 +70,7 @@ abstract class ApiQueryBase extends ApiBase { * Public caching will only be allowed if *all* the modules that supply * data for a given request return a cache mode of public. * + * @stable for overriding * @param array $params * @return string */ @@ -81,6 +85,7 @@ abstract class ApiQueryBase extends ApiBase { * Note this only makes sense for 'prop' modules, as 'list' and 'meta' * modules should not be using the pageset. * + * @stable for overriding * @param ApiPageSet $pageSet */ public function requestExtraData( $pageSet ) { @@ -108,6 +113,7 @@ abstract class ApiQueryBase extends ApiBase { /** * Get the Query database connection (read-only) + * @stable for overriding * @return IDatabase */ protected function getDB() { @@ -133,6 +139,7 @@ abstract class ApiQueryBase extends ApiBase { /** * Get the PageSet object to work on + * @stable for overriding * @return ApiPageSet */ protected function getPageSet() { diff --git a/includes/api/ApiQueryGeneratorBase.php b/includes/api/ApiQueryGeneratorBase.php index 35ce7560800..6c94e58e373 100644 --- a/includes/api/ApiQueryGeneratorBase.php +++ b/includes/api/ApiQueryGeneratorBase.php @@ -21,6 +21,8 @@ */ /** + * @stable for subclassing + * * @ingroup API */ abstract class ApiQueryGeneratorBase extends ApiQueryBase { diff --git a/includes/api/ApiQueryRevisionsBase.php b/includes/api/ApiQueryRevisionsBase.php index b52e3e92fa3..ca36ad6e69a 100644 --- a/includes/api/ApiQueryRevisionsBase.php +++ b/includes/api/ApiQueryRevisionsBase.php @@ -32,6 +32,8 @@ use Wikimedia\ParamValidator\TypeDef\IntegerDef; /** * A base class for functions common to producing a list of revisions. * + * @stable for subclassing + * * @ingroup API */ abstract class ApiQueryRevisionsBase extends ApiQueryGeneratorBase { @@ -655,6 +657,12 @@ abstract class ApiQueryRevisionsBase extends ApiQueryGeneratorBase { return $vals; } + /** + * @stable for overriding + * @param array $params + * + * @return string + */ public function getCacheMode( $params ) { if ( $this->userCanSeeRevDel() ) { return 'private'; @@ -663,6 +671,11 @@ abstract class ApiQueryRevisionsBase extends ApiQueryGeneratorBase { return 'public'; } + /** + * @stable for overriding + * @return array + * @throws MWException + */ public function getAllowedParams() { $slotRoles = MediaWikiServices::getInstance()->getSlotRoleRegistry()->getKnownRoles(); sort( $slotRoles, SORT_STRING );