Thijs/wiki.techinc.nl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

pager: Clean up file headers and @ingroup

Browse source 
Follows similar commits to the objectcache, rdbms, filerepo,
jobqueue components and other areas [1].

* Remove duplicate descriptions from file blocks in favour of class
  doc blocks. This reduces needless duplication and was often
  incorrect or outdated, and helps (ironically) to make the file header
  more consistently visually ignorable.

* Remove `ingroup` from file blocks in class files as otherwise
  the file is indexed twice (e.g. in Doxygen) which makes navigation
  more messy.

* Fix non-standard `@unstable for implementation` annotations
  in favour of `@stable to type` as per T257789 and
  <https://www.mediawiki.org/wiki/Stable_interface_policy>.

  While at it, fix the only other outstanding uses of `@stable for`
  in core as well in a handful of context/, logging/ and search/
  files.

[1] https://gerrit.wikimedia.org/r/q/message:ingroup+owner:Krinkle

Bug: T257789
Change-Id: Ided3c5ab69e1b587b1b76a3c97a7cdb88f21e130
This commit is contained in:
Timo Tijhof 2022-09-29 21:05:08 +01:00
parent 5c89b4e248
commit ee5ad165e6
12 changed files with 48 additions and 50 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

19
includes/content/Content.php
View file

@ -1,8 +1,5 @@
<?php
/**
* A content object represents page content, e.g. the text to show on a page.
* Content objects have no knowledge about how they relate to wiki pages.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
@ -18,19 +15,21 @@
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
* http://www.gnu.org/copyleft/gpl.html
*
* @since 1.21
*
* @file
* @ingroup Content
*
* @author Daniel Kinzler
*/
/**
* Base interface for content objects.
* Base interface for representing page content.
*
* A content object represents page content, e.g. the text to show on a page.
* Content objects have no knowledge about how they relate to wiki pages.
*
* Must not be implemented directly by extensions, extend AbstractContent instead.
*
* @stable to type
* @since 1.21
* @ingroup Content
* @unstable for implementation, extensions should extend AbstractContent instead.
* @author Daniel Kinzler
*/
interface Content {

2
includes/context/ContextSource.php
View file

@ -15,7 +15,6 @@
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
* http://www.gnu.org/copyleft/gpl.html
*
* @author Happy-melon
* @file
*/
use MediaWiki\MediaWikiServices;
@ -29,6 +28,7 @@ use Wikimedia\NonSerializable\NonSerializableTrait;
*
* @stable to extend
* @since 1.18
* @author Happy-melon
*/
abstract class ContextSource implements IContextSource {
use NonSerializableTrait;

9
includes/context/IContextSource.php
View file

@ -15,9 +15,6 @@
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
* http://www.gnu.org/copyleft/gpl.html
*
* @since 1.18
*
* @author Happy-melon
* @file
*/
@ -53,7 +50,11 @@ use MediaWiki\Session\CsrfTokenSetProvider;
* 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.
* Must not be implemented directly by extensions, extend ContextSource instead.
*
* @since 1.18
* @stable to type
* @author Happy-melon
*/
interface IContextSource extends MessageLocalizer, CsrfTokenSetProvider {

14
includes/logging/LogEntry.php
View file

@ -1,7 +1,5 @@
<?php
/**
* Contains a class for dealing with individual log entries
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
@ -18,18 +16,20 @@
* http://www.gnu.org/copyleft/gpl.html
*
* @file
* @author Niklas Laxström
* @license GPL-2.0-or-later
* @since 1.19
*/
use MediaWiki\User\UserIdentity;
/**
* Interface for log entries. Every log entry has these methods.
* An individual log entry.
*
* @unstable for implementation, extensions should subclass LogEntryBase instead.
* This is the basis for methods that all log entries support.
*
* Must not be implemented directly by extensions, extend LogEntryBase instead.
*
* @stable to type
* @since 1.19
* @author Niklas Laxström
*/
interface LogEntry {

4
includes/pager/AlphabeticPager.php
View file

@ -1,7 +1,5 @@
<?php
/**
* Efficient paging for SQL queries.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
@ -18,11 +16,11 @@
* http://www.gnu.org/copyleft/gpl.html
*
* @file
* @ingroup Pager
*/
/**
* IndexPager with an alphabetic list and a formatted navigation bar
*
* @stable to extend
* @ingroup Pager
*/

20
includes/pager/IndexPager.php
View file

@ -1,7 +1,5 @@
<?php
/**
* Efficient paging for SQL queries.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
@ -18,7 +16,6 @@
* http://www.gnu.org/copyleft/gpl.html
*
* @file
* @ingroup Pager
*/
use MediaWiki\HookContainer\ProtectedHookAccessorTrait;
@ -30,8 +27,11 @@ use Wikimedia\Rdbms\IDatabase;
use Wikimedia\Rdbms\IResultWrapper;
/**
* IndexPager is an efficient pager which uses a (roughly unique) index in the
* data set to implement paging, rather than a "LIMIT offset,limit" clause.
* Efficient paging for SQL queries that use a (roughly unique) index.
*
* This is for paging through data sets stored in tables with a unique
* index, instead of a naive "LIMIT offset,limit" clause.
*
* In MySQL, such a limit/offset clause requires counting through the
* specified number of offset rows to find the desired data, which can be
* expensive for large offsets.
@ -63,11 +63,11 @@ use Wikimedia\Rdbms\IResultWrapper;
* from the query. This naturally produces either the first page or the
* last page depending on the dir parameter.
*
* Subclassing the pager to implement concrete functionality should be fairly
* simple, please see the examples in HistoryAction.php and
* SpecialBlockList.php. You just need to override formatRow(),
* getQueryInfo() and getIndexField(). Don't forget to call the parent
* constructor if you override it.
* Subclassing the pager to implement concrete functionality should be fairly
* simple, please see the examples in HistoryAction.php and
* SpecialBlockList.php. You just need to override formatRow(),
* getQueryInfo() and getIndexField(). Don't forget to call the parent
* constructor if you override it.
*
* @stable to extend
* @ingroup Pager

10
includes/pager/Pager.php
View file

@ -1,7 +1,5 @@
<?php
/**
* Efficient paging for SQL queries.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
@ -18,7 +16,6 @@
* http://www.gnu.org/copyleft/gpl.html
*
* @file
* @ingroup Pager
*/
/**
@ -26,9 +23,12 @@
*/
/**
* Basic pager interface.
* Basic pager interface for efficient paging through SQL queries.
*
* @unstable for implementation, extensions should extend IndexPager or one of its subclasses.
* Must not be implemented directly by extensions,
* instead extend IndexPager or one of its subclasses.
*
* @stable to type
* @ingroup Pager
*/
interface Pager {

2
includes/pager/RangeChronologicalPager.php
View file

@ -16,12 +16,12 @@
* http://www.gnu.org/copyleft/gpl.html
*
* @file
* @ingroup Pager
*/
use Wikimedia\Timestamp\TimestampException;
/**
* Pager for filtering by a range of dates.
*
* @stable to extend
* @ingroup Pager
*/

3
includes/pager/ReverseChronologicalPager.php
View file

@ -16,13 +16,12 @@
* http://www.gnu.org/copyleft/gpl.html
*
* @file
* @ingroup Pager
*/
use Wikimedia\Timestamp\TimestampException;
/**
* Efficient paging for SQL queries.
* IndexPager with a formatted navigation bar.
*
* @stable to extend
* @ingroup Pager
*/

4
includes/pager/TablePager.php
View file

@ -1,7 +1,5 @@
<?php
/**
* Efficient paging for SQL queries.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
@ -18,13 +16,13 @@
* http://www.gnu.org/copyleft/gpl.html
*
* @file
* @ingroup Pager
*/
use MediaWiki\Linker\LinkRenderer;
/**
* Table-based display with a user-selectable sort order
*
* @stable to extend
* @ingroup Pager
*/

6
includes/search/ISearchResultSet.php
View file

@ -2,10 +2,10 @@
/**
* A set of SearchEngine results.
* 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.
* Must not be implemented directly by extensions, extend BaseSearchResultSet instead.
*
* @stable to type
* @see BaseSearchResultSet
* @ingroup Search
*/

5
includes/search/SearchIndexField.php
View file

@ -1,7 +1,10 @@
<?php
/**
* Definition of a mapping for the search index field.
* @unstable for implementation, extensions should subclass the SearchIndexFieldDefinition.
*
* Must not be implemented directly by extensions, extend SearchIndexFieldDefinition instead.
*
* @stable to type
* @since 1.28
*/
interface SearchIndexField {