Merge "Mark pager base classes as stable for subclassing."

includes/pager/AlphabeticPager.php

@@ -23,6 +23,7 @@
 
 /**
  * IndexPager with an alphabetic list and a formatted navigation bar
+ * @stable for subclassing
  * @ingroup Pager
  */
 abstract class AlphabeticPager extends IndexPager {
@@ -31,6 +32,8 @@ abstract class AlphabeticPager extends IndexPager {
 	 * Shamelessly stolen bits from ReverseChronologicalPager,
 	 * didn't want to do class magic as may be still revamped
 	 *
+	 * @stable for overriding
+	 *
 	 * @return string HTML
 	 */
 	public function getNavigationBar() {
@@ -100,6 +103,8 @@ abstract class AlphabeticPager extends IndexPager {
 	 * array whose keys must exactly match the keys of the array returned
 	 * by getIndexField(), and whose values are message keys.
 	 *
+	 * @stable for overriding
+	 *
 	 * @return array
 	 */
 	protected function getOrderTypeMessages() {

includes/pager/IndexPager.php

@@ -68,6 +68,7 @@ use Wikimedia\Rdbms\IResultWrapper;
  *  getQueryInfo() and getIndexField(). Don't forget to call the parent
  *  constructor if you override it.
  *
+ * @stable for subclassing
  * @ingroup Pager
  */
 abstract class IndexPager extends ContextSource implements Pager {
@@ -165,6 +166,12 @@ abstract class IndexPager extends ContextSource implements Pager {
 	/** @var LinkRenderer */
 	private $linkRenderer;
 
+	/**
+	 * @stable for calling
+	 *
+	 * @param IContextSource|null $context
+	 * @param LinkRenderer|null $linkRenderer
+	 */
 	public function __construct( IContextSource $context = null, LinkRenderer $linkRenderer = null ) {
 		if ( $context ) {
 			$this->setContext( $context );
@@ -242,6 +249,8 @@ abstract class IndexPager extends ContextSource implements Pager {
 	 * Do the query, using information from the object context. This function
 	 * has been kept minimal to make it overridable if necessary, to allow for
 	 * result sets formed from multiple DB queries.
+	 *
+	 * @stable for overriding
 	 */
 	public function doQuery() {
 		$defaultOrder = ( $this->mDefaultDirection === self::DIR_ASCENDING )
@@ -309,6 +318,8 @@ abstract class IndexPager extends ContextSource implements Pager {
 	 *
 	 * Verifies limit is between 1 and 5000
 	 *
+	 * @stable for overriding
+	 *
 	 * @param int|string $limit
 	 */
 	public function setLimit( $limit ) {
@@ -346,6 +357,8 @@ abstract class IndexPager extends ContextSource implements Pager {
 	 * Extract some useful data from the result object for use by
 	 * the navigation bar, put it into $this
 	 *
+	 * @stable for overriding
+	 *
 	 * @param bool $isFirst False if there are rows before those fetched (i.e.
 	 *     if a "previous" link would make sense)
 	 * @param int $limit Exact query limit
@@ -409,6 +422,8 @@ abstract class IndexPager extends ContextSource implements Pager {
 	/**
 	 * Get some text to go in brackets in the "function name" part of the SQL comment
 	 *
+	 * @stable for overriding
+	 *
 	 * @return string
 	 */
 	protected function getSqlComment() {
@@ -420,6 +435,8 @@ abstract class IndexPager extends ContextSource implements Pager {
 	 *
 	 * @note For b/c, query direction is true for ascending and false for descending
 	 *
+	 * @stable for overriding
+	 *
 	 * @param string $offset Index offset, inclusive
 	 * @param int $limit Exact query limit
 	 * @param bool $order IndexPager::QUERY_ASCENDING or IndexPager::QUERY_DESCENDING
@@ -437,6 +454,8 @@ abstract class IndexPager extends ContextSource implements Pager {
 	 *
 	 * @note For b/c, query direction is true for ascending and false for descending
 	 *
+	 * @stable for overriding
+	 *
 	 * @param int|string $offset Index offset, inclusive
 	 * @param int $limit Exact query limit
 	 * @param bool $order IndexPager::QUERY_ASCENDING or IndexPager::QUERY_DESCENDING
@@ -549,6 +568,8 @@ abstract class IndexPager extends ContextSource implements Pager {
 	/**
 	 * Pre-process results; useful for performing batch existence checks, etc.
 	 *
+	 * @stable for overriding
+	 *
 	 * @param IResultWrapper $result
 	 */
 	protected function preprocessResults( $result ) {
@@ -558,6 +579,8 @@ abstract class IndexPager extends ContextSource implements Pager {
 	 * Get the formatted result list. Calls getStartBody(), formatRow() and
 	 * getEndBody(), concatenates the results and returns them.
 	 *
+	 * @stable for overriding
+	 *
 	 * @return string
 	 */
 	public function getBody() {
@@ -598,6 +621,8 @@ abstract class IndexPager extends ContextSource implements Pager {
 	/**
 	 * Make a self-link
 	 *
+	 * @stable for overriding
+	 *
 	 * @param string $text Text displayed on the link
 	 * @param array|null $query Associative array of parameter to be in the query string
 	 * @param string|null $type Link type used to create additional attributes, like "rel", "class" or
@@ -635,6 +660,8 @@ abstract class IndexPager extends ContextSource implements Pager {
 	 * after doQuery() was called. This will be called only if there
 	 * are rows in the result set.
 	 *
+	 * @stable for overriding
+	 *
 	 * @return void
 	 */
 	protected function doBatchLookups() {
@@ -653,6 +680,8 @@ abstract class IndexPager extends ContextSource implements Pager {
 	/**
 	 * Hook into getBody() for the end of the list
 	 *
+	 * @stable for overriding
+	 *
 	 * @return string
 	 */
 	protected function getEndBody() {
@@ -663,6 +692,8 @@ abstract class IndexPager extends ContextSource implements Pager {
 	 * Hook into getBody(), for the bit between the start and the
 	 * end when there are no rows
 	 *
+	 * @stable for overriding
+	 *
 	 * @return string
 	 */
 	protected function getEmptyBody() {
@@ -674,6 +705,8 @@ abstract class IndexPager extends ContextSource implements Pager {
 	 * By default, all parameters passed in the URL are used, except for a
 	 * short blacklist.
 	 *
+	 * @stable for overriding
+	 *
 	 * @return array Associative array
 	 */
 	public function getDefaultQuery() {
@@ -705,6 +738,8 @@ abstract class IndexPager extends ContextSource implements Pager {
 	/**
 	 * Get a URL query array for the prev, next, first and last links.
 	 *
+	 * @stable for overriding
+	 *
 	 * @return array
 	 */
 	public function getPagingQueries() {
@@ -744,6 +779,7 @@ abstract class IndexPager extends ContextSource implements Pager {
 
 	/**
 	 * Returns whether to show the "navigation bar"
+	 * @stable for overriding
 	 *
 	 * @return bool
 	 */
@@ -882,6 +918,8 @@ abstract class IndexPager extends ContextSource implements Pager {
 	 * page_len,page_id avoids temp tables (given a page_len index). This would
 	 * also work if page_id was non-unique but we had a page_len,page_id index.
 	 *
+	 * @stable for overriding
+	 *
 	 * @return string[]|array[]
 	 */
 	protected function getExtraSortFields() {
@@ -905,6 +943,8 @@ abstract class IndexPager extends ContextSource implements Pager {
 	 * particular instantiation, which is a single value.  This is the set of
 	 * all defaults for the class.
 	 *
+	 * @stable for overriding
+	 *
 	 * @return bool
 	 */
 	protected function getDefaultDirections() {

includes/pager/RangeChronologicalPager.php

@@ -22,6 +22,7 @@ use Wikimedia\Timestamp\TimestampException;
 
 /**
  * Pager for filtering by a range of dates.
+ * @stable for subclassing
  * @ingroup Pager
  */
 abstract class RangeChronologicalPager extends ReverseChronologicalPager {
@@ -35,6 +36,8 @@ abstract class RangeChronologicalPager extends ReverseChronologicalPager {
 	 * Also supports only having a start or end timestamp.
 	 * Assumes that the start timestamp comes before the end timestamp.
 	 *
+	 * @stable for overriding
+	 *
 	 * @param string $startStamp Timestamp of the beginning of the date range (or empty)
 	 * @param string $endStamp Timestamp of the end of the date range (or empty)
 	 * @return array|null Database conditions to satisfy the specified date range
@@ -72,6 +75,8 @@ abstract class RangeChronologicalPager extends ReverseChronologicalPager {
 	 * Takes ReverseChronologicalPager::getDateCond parameters and repurposes
 	 * them to work with timestamp-based getDateRangeCond.
 	 *
+	 * @stable for overriding
+	 *
 	 * @param int $year Year up to which we want revisions
 	 * @param int $month Month up to which we want revisions
 	 * @param int $day [optional] Day up to which we want revisions. Default is end of month.
@@ -92,6 +97,8 @@ abstract class RangeChronologicalPager extends ReverseChronologicalPager {
 	/**
 	 * Build variables to use by the database wrapper.
 	 *
+	 * @stable for overriding
+	 *
 	 * @param string $offset Index offset, inclusive
 	 * @param int $limit Exact query limit
 	 * @param bool $order IndexPager::QUERY_ASCENDING or IndexPager::QUERY_DESCENDING

includes/pager/ReverseChronologicalPager.php

@@ -23,6 +23,7 @@ use Wikimedia\Timestamp\TimestampException;
 /**
  * Efficient paging for SQL queries.
  * IndexPager with a formatted navigation bar.
+ * @stable for subclassing
  * @ingroup Pager
  */
 abstract class ReverseChronologicalPager extends IndexPager {
@@ -35,6 +36,10 @@ abstract class ReverseChronologicalPager extends IndexPager {
 	/** @var int */
 	public $mDay;
 
+	/**
+	 * @stable for overriding
+	 * @return string
+	 */
 	public function getNavigationBar() {
 		if ( !$this->isNavigationBarShown() ) {
 			return '';
@@ -69,6 +74,8 @@ abstract class ReverseChronologicalPager extends IndexPager {
 	 * Set and return the mOffset timestamp such that we can get all revisions with
 	 * a timestamp up to the specified parameters.
 	 *
+	 * @stable for overriding
+	 *
 	 * @param int $year Year up to which we want revisions
 	 * @param int $month Month up to which we want revisions
 	 * @param int $day [optional] Day up to which we want revisions. Default is end of month.

includes/pager/TablePager.php

@@ -25,6 +25,7 @@ use MediaWiki\Linker\LinkRenderer;
 
 /**
  * Table-based display with a user-selectable sort order
+ * @stable for subclassing
  * @ingroup Pager
  */
 abstract class TablePager extends IndexPager {
@@ -34,6 +35,12 @@ abstract class TablePager extends IndexPager {
 	/** @var stdClass */
 	protected $mCurrentRow;
 
+	/**
+	 * @stable for calling
+	 *
+	 * @param IContextSource|null $context
+	 * @param LinkRenderer|null $linkRenderer
+	 */
 	public function __construct( IContextSource $context = null, LinkRenderer $linkRenderer = null ) {
 		if ( $context ) {
 			$this->setContext( $context );
@@ -112,6 +119,7 @@ abstract class TablePager extends IndexPager {
 	}
 
 	/**
+	 * @stable for overriding
 	 * @return string
 	 */
 	protected function getStartBody() {
@@ -163,6 +171,7 @@ abstract class TablePager extends IndexPager {
 	}
 
 	/**
+	 * @stable for overriding
 	 * @return string
 	 */
 	protected function getEndBody() {
@@ -180,6 +189,7 @@ abstract class TablePager extends IndexPager {
 	}
 
 	/**
+	 * @stable for overriding
 	 * @param stdClass $row
 	 * @return string HTML
 	 */
@@ -207,6 +217,8 @@ abstract class TablePager extends IndexPager {
 	/**
 	 * Get a class name to be applied to the given row.
 	 *
+	 * @stable for overriding
+	 *
 	 * @param object $row The database result row
 	 * @return string
 	 */
@@ -217,6 +229,8 @@ abstract class TablePager extends IndexPager {
 	/**
 	 * Get attributes to be applied to the given row.
 	 *
+	 * @stable for overriding
+	 *
 	 * @param object $row The database result row
 	 * @return array Array of attribute => value
 	 */
@@ -242,6 +256,8 @@ abstract class TablePager extends IndexPager {
 	 * take this as an excuse to hardcode styles; use classes and
 	 * CSS instead.  Row context is available in $this->mCurrentRow
 	 *
+	 * @stable for overriding
+	 *
 	 * @param string $field The column
 	 * @param string $value The cell contents
 	 * @return array Array of attr => value
@@ -252,6 +268,7 @@ abstract class TablePager extends IndexPager {
 
 	/**
 	 * @inheritDoc
+	 * @stable for overriding
 	 */
 	public function getIndexField() {
 		return $this->mSort;
@@ -259,6 +276,8 @@ abstract class TablePager extends IndexPager {
 
 	/**
 	 * TablePager relies on `mw-datatable` for styling, see T214208
+	 *
+	 * @stable for overriding
 	 * @return string
 	 */
 	protected function getTableClass() {
@@ -266,6 +285,7 @@ abstract class TablePager extends IndexPager {
 	}
 
 	/**
+	 * @stable for overriding
 	 * @return string
 	 */
 	protected function getNavClass() {
@@ -273,6 +293,7 @@ abstract class TablePager extends IndexPager {
 	}
 
 	/**
+	 * @stable for overriding
 	 * @return string
 	 */
 	protected function getSortHeaderClass() {
@@ -281,6 +302,8 @@ abstract class TablePager extends IndexPager {
 
 	/**
 	 * A navigation bar with images
+	 *
+	 * @stable for overriding
 	 * @return string HTML
 	 */
 	public function getNavigationBar() {
@@ -324,6 +347,8 @@ abstract class TablePager extends IndexPager {
 
 	/**
 	 * ResourceLoader modules that must be loaded to provide correct styling for this pager
+	 *
+	 * @stable for overriding
 	 * @since 1.24
 	 * @return string[]
 	 */