Stability annotations for interfaces.

Per the Stable Interface Policy, PHP interfaces should not be
directly implemented by extensions, unless they are marked to be safe
for that purpose.

Bug: T247862
Change-Id: Idd5783b70fc00c03d57f5b1a887f0e47c4d7b146

includes/Rest/ResponseInterface.php

@@ -35,6 +35,8 @@ use Psr\Http\Message\StreamInterface;
 /**
  * An interface similar to PSR-7's ResponseInterface, the primary difference
  * being that it is mutable.
+ *
+ * @stable for implementing
  */
 interface ResponseInterface {
 	// ResponseInterface

includes/Rest/Validator/BodyValidator.php

@@ -7,6 +7,8 @@ use MediaWiki\Rest\RequestInterface;
 
 /**
  * Interface for validating a request body
+ *
+ * @stable for implementation
  */
 interface BodyValidator {
 

includes/api/ApiSerializable.php

@@ -29,6 +29,8 @@
  *   code to maintain compatibility with older MediaWiki while still taking
  *   advantage of this where it exists.
  *
+ * @stable for implementation
+ *
  * @ingroup API
  * @since 1.25
  */

includes/config/Config.php

@@ -23,6 +23,8 @@
 /**
  * Interface for configuration instances
  *
+ * @stable for implementation
+ *
  * @since 1.23
  */
 interface Config {

includes/config/MutableConfig.php

@@ -23,6 +23,8 @@
 /**
  * Interface for mutable configuration instances
  *
+ * @stable for implementation
+ *
  * @since 1.24
  */
 interface MutableConfig {

includes/content/Content.php

@@ -30,6 +30,7 @@
  * Base interface for content objects.
  *
  * @ingroup Content
+ * @unstable for implementation, extensions should extend AbstractContent instead.
  */
 interface Content {
 

includes/context/IContextSource.php

@@ -49,6 +49,8 @@
  * from Config itself). Objects that represent persistent data stores do not
  * belong here either. Session state changes should only be propagated on
  * shutdown by separate persistence handler objects, for example.
+ *
+ * @unstable for implementation, extensions should subclass ContextSource instead.
  */
 interface IContextSource extends MessageLocalizer {
 

includes/dao/IDBAccessObject.php

@@ -50,6 +50,8 @@
  *   - e) otherwise, do the updates
  *   - f) Commit transaction
  *
+ * @stable for implementation
+ *
  * @since 1.20
  */
 interface IDBAccessObject {

includes/debug/logger/Spi.php

@@ -30,6 +30,8 @@ namespace MediaWiki\Logger;
  * and registers it via the LoggerFactory::registerProvider() static method.
  *
  * @see \MediaWiki\Logger\LoggerFactory
+ * @stable for implementation
+ *
  * @since 1.25
  * @copyright © 2014 Wikimedia Foundation and contributors
  */

includes/deferred/DeferrableCallback.php

@@ -3,6 +3,8 @@
 /**
  * Callback wrapper that has an originating method
  *
+ * @stable for implementation
+ *
  * @since 1.28
  */
 interface DeferrableCallback {

includes/deferred/DeferrableUpdate.php

@@ -4,6 +4,8 @@
  * Interface that deferrable updates should implement. Basically required so we
  * can validate input on DeferredUpdates::addUpdate()
  *
+ * @stable for implementation
+ *
  * @since 1.19
  */
 interface DeferrableUpdate {

includes/deferred/EnqueueableDataUpdate.php

@@ -5,6 +5,8 @@
  * Such updates must be representable using IJobSpecification, so that
  * they can be serialized into jobs and enqueued for later execution
  *
+ * @stable for implementation
+ *
  * @since 1.27
  */
 interface EnqueueableDataUpdate {

includes/deferred/MergeableUpdate.php

@@ -13,6 +13,8 @@
  *
  * The purges for urls A and B will all happen after the $deleteContentUrlsB update.
  *
+ * @stable for implementation
+ *
  * @since 1.27
  */
 interface MergeableUpdate extends DeferrableUpdate {

includes/deferred/TransactionRoundAwareUpdate.php

@@ -4,6 +4,8 @@
  * Deferrable update that specifies whether it must run outside of any explicit
  * LBFactory transaction round or must run inside of a round owned by doUpdate().
  *
+ * @stable for implementation
+ *
  * @since 1.34
  */
 interface TransactionRoundAwareUpdate {

includes/exception/ILocalizedException.php

@@ -21,6 +21,8 @@
 /**
  * Interface for MediaWiki-localized exceptions
  *
+ * @stable for implementation
+ *
  * @since 1.29
  * @ingroup Exception
  */

includes/jobqueue/GenericParameterJob.php

@@ -23,6 +23,8 @@
 /**
  * Interface for generic jobs only uses the parameters field and are JSON serializable
  *
+ * @stable for implementation
+ *
  * @ingroup JobQueue
  * @since 1.33
  */

includes/jobqueue/RunnableJob.php

@@ -29,6 +29,8 @@
  * loaded by the application for the local DB domain. In that case, the general-purpose
  * JobSpecification class can be used instead.
  *
+ * @stable for implementation
+ *
  * @ingroup JobQueue
  * @since 1.33
  */

includes/language/MessageLocalizer.php

@@ -21,6 +21,8 @@
 /**
  * Interface for localizing messages in MediaWiki
  *
+ * @stable for implementing
+ *
  * @since 1.30
  * @ingroup Language
  */

includes/libs/MessageSpecifier.php

@@ -18,6 +18,9 @@
  * @file
  */
 
+/**
+ * @stable for implementing
+ */
 interface MessageSpecifier {
 	/**
 	 * Returns the message key

includes/libs/rdbms/database/position/DBMasterPos.php

@@ -8,6 +8,8 @@ use Serializable;
  * An object representing a master or replica DB position in a replicated setup.
  *
  * The implementation details of this opaque type are up to the database subclass.
+ *
+ * @stable for implementation
  */
 interface DBMasterPos extends Serializable {
 	/**

includes/libs/stats/IBufferingStatsdDataFactory.php

@@ -6,6 +6,8 @@ use Liuggio\StatsdClient\Factory\StatsdDataFactoryInterface;
 /**
  * MediaWiki adaptation of StatsdDataFactory that provides buffering functionality.
  *
+ * @stable for implementation
+ *
  * @see BufferingStatsdDataFactory
  */
 interface IBufferingStatsdDataFactory extends StatsdDataFactoryInterface {

includes/libs/stats/StatsdAwareInterface.php

@@ -5,6 +5,8 @@ use Liuggio\StatsdClient\Factory\StatsdDataFactoryInterface;
 /**
  * Describes a Statsd aware interface
  *
+ * @stable for implementation
+ *
  * @since 1.27
  * @author Addshore
  */

includes/logging/LogEntry.php

@@ -26,6 +26,7 @@
 /**
  * Interface for log entries. Every log entry has these methods.
  *
+ * @unstable for implementation, extensions should subclass LogEntryBase instead.
  * @since 1.19
  */
 interface LogEntry {

includes/pager/Pager.php

@@ -27,6 +27,8 @@
 
 /**
  * Basic pager interface.
+ *
+ * @unstable for implementation, extensions should extend IndexPager or one of its subclasses.
  * @ingroup Pager
  */
 interface Pager {

includes/preferences/PreferencesFactory.php

@@ -48,6 +48,8 @@ use User;
  *
  * Once fields have been retrieved and validated, submission logic is handed over to the
  * submitForm() method of this interface.
+ *
+ * @stable for implementation
  */
 interface PreferencesFactory {
 

includes/rcfeed/RCFeedFormatter.php

@@ -22,6 +22,7 @@
 /**
  * Interface for RC feed formatters
  *
+ * @stable for implementing
  * @since 1.22
  */
 interface RCFeedFormatter {

includes/search/ISearchResultSet.php

@@ -5,6 +5,7 @@
  * Must not be directly implemented by extension, please extend BaseSearchResultSet instead.
  * This interface must only be used for type hinting.
  *
+ * @unstable for implementation, extensions should extend the BaseSearchResultSet base class.
  * @see BaseSearchResultSet
  * @ingroup Search
  */

includes/search/PaginatingSearchEngine.php

@@ -7,6 +7,8 @@
  *
  * SearchEngine implementations not implementing this interface will have
  * an over-fetch performed to determine next page availability.
+ *
+ * @stable for implementation
  */
 interface PaginatingSearchEngine {
 }

includes/search/ResultAugmentor.php

@@ -2,6 +2,7 @@
 
 /**
  * Augment search results.
+ * @stable for implementation
  */
 interface ResultAugmentor {
 	/**

includes/search/ResultSetAugmentor.php

@@ -2,6 +2,7 @@
 
 /**
  * Augment search results.
+ * @stable for implementation
  */
 interface ResultSetAugmentor {
 	/**

includes/search/SearchIndexField.php

@@ -1,6 +1,7 @@
 <?php
 /**
  * Definition of a mapping for the search index field.
+ * @unstable for implementation, extensions should subclass the SearchIndexFieldDefinition.
  * @since 1.28
  */
 interface SearchIndexField {

includes/utils/RowUpdateGenerator.php

@@ -17,6 +17,8 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
+ * @stable for implementation
+ *
  * @file
  * @ingroup Maintenance
  */