Mark API base classes as extensible

This marks API base classes as stable for extending per the
Stable Interface Policy.

Bug: T247862
Change-Id: I164192ba3d013d8bc98a8b9c6db10e3dd1e58b23

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

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() {

includes/api/ApiQueryGeneratorBase.php

@@ -21,6 +21,8 @@
  */
 
 /**
+ * @stable for subclassing
+ *
  * @ingroup API
  */
 abstract class ApiQueryGeneratorBase extends ApiQueryBase {

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 );