Use @internal instead of @private per policy

https://www.mediawiki.org/wiki/Stable_interface_policy mandates the use
of @internal. The semantics of @private was never properly defined.

Bug: T247862
Change-Id: I4c7c6e7b5a80e86456965521f88d1dfa7d698f84

includes/ActorMigration.php

@@ -109,7 +109,7 @@ class ActorMigration {
 	private $stage;
 
 	/**
-	 * @private
+	 * @internal
 	 * @param int $stage
 	 */
 	public function __construct( $stage ) {

includes/AutoLoader.php

@@ -31,7 +31,7 @@ class AutoLoader {
 	protected static $autoloadLocalClassesLower = null;
 
 	/**
-	 * @private Only public for ExtensionRegistry
+	 * @internal Only public for ExtensionRegistry
 	 * @var string[] Namespace (ends with \) => Path (ends with /)
 	 */
 	public static $psr4Namespaces = [];
@@ -122,7 +122,7 @@ class AutoLoader {
 	 * The namespaces should follow the PSR-4 standard for autoloading
 	 *
 	 * @see <https://www.php-fig.org/psr/psr-4/>
-	 * @private Only public for usage in AutoloadGenerator
+	 * @internal Only public for usage in AutoloadGenerator
 	 * @codeCoverageIgnore
 	 * @since 1.31
 	 * @return string[]

includes/CategoryViewer.php

@@ -525,7 +525,7 @@ class CategoryViewer extends ContextSource {
 	 * @param array $articles_start_char
 	 * @param int $cutoff
 	 * @return string
-	 * @private
+	 * @internal
 	 */
 	private function formatList( $articles, $articles_start_char, $cutoff = 6 ) {
 		$list = '';
@@ -556,7 +556,7 @@ class CategoryViewer extends ContextSource {
 	 * @param string[] $articles HTML links to each article
 	 * @param string[] $articles_start_char The header characters for each article
 	 * @return string HTML to output
-	 * @private
+	 * @internal
 	 */
 	public static function columnList( $articles, $articles_start_char ) {
 		$columns = array_combine( $articles, $articles_start_char );
@@ -597,7 +597,7 @@ class CategoryViewer extends ContextSource {
 	 * @param string[] $articles HTML links to each article
 	 * @param string[] $articles_start_char The header characters for each article
 	 * @return string HTML to output
-	 * @private
+	 * @internal
 	 */
 	public static function shortList( $articles, $articles_start_char ) {
 		$r = '<h3>' . htmlspecialchars( $articles_start_char[0] ) . "</h3>\n";

includes/CommentStoreComment.php

@@ -41,7 +41,7 @@ class CommentStoreComment {
 	public $data;
 
 	/**
-	 * @private For use by CommentStore only. Use self::newUnsavedComment() instead.
+	 * @internal For use by CommentStore only. Use self::newUnsavedComment() instead.
 	 * @param int|null $id
 	 * @param string $text
 	 * @param Message|null $message

includes/EditPage.php

@@ -1559,7 +1559,7 @@ class EditPage implements IEditObject {
 	 *
 	 * @param WebRequest &$request
 	 * @return bool
-	 * @private
+	 * @internal
 	 */
 	public function tokenOk( &$request ) {
 		$token = $request->getVal( 'wpEditToken' );

includes/GlobalFunctions.php

@@ -1252,7 +1252,7 @@ function wfMessageFallback( ...$keys ) {
  * @param string $message
  * @param array $args
  * @return string
- * @private
+ * @internal
  */
 function wfMsgReplaceArgs( $message, $args ) {
 	# Fix windows line-endings
@@ -1733,7 +1733,7 @@ function wfAcceptToPrefs( $accept, $def = '*/*' ) {
  * @param string $type
  * @param array $avail
  * @return string
- * @private
+ * @internal
  */
 function mimeTypeMatch( $type, $avail ) {
 	if ( array_key_exists( $type, $avail ) ) {

includes/MagicWord.php

@@ -132,7 +132,7 @@ class MagicWord {
 
 	/**
 	 * Preliminary initialisation
-	 * @private
+	 * @internal
 	 */
 	public function initRegex() {
 		// Sort the synonyms by length, descending, so that the longest synonym

includes/MovePage.php

@@ -745,7 +745,7 @@ class MovePage {
 	 * Move a file associated with a page to a new location.
 	 * Can also be used to revert after a DB failure.
 	 *
-	 * @private
+	 * @internal
 	 * @param Title $oldTitle Old location to move the file from.
 	 * @param Title $newTitle New location to move the file to.
 	 * @return Status

includes/Revision.php

@@ -359,7 +359,7 @@ class Revision implements IDBAccessObject {
 	 * Since 1.35, constructing with anything other than a RevisionRecord is hard deprecated
 	 * (since 1.31 the entire class is deprecated)
 	 *
-	 * @private
+	 * @internal
 	 */
 	public function __construct( $row, $queryFlags = 0, Title $title = null ) {
 		global $wgUser;

includes/Setup.php

@@ -445,7 +445,7 @@ if ( $wgEnableEmail ) {
 
 /**
  * Definitions of the NS_ constants are in Defines.php
- * @private
+ * @internal
  */
 $wgCanonicalNamespaceNames = NamespaceInfo::CANONICAL_NAMES;
 

includes/Title.php

@@ -69,7 +69,7 @@ class Title implements LinkTarget, IDBAccessObject {
 	/**
 	 * @name Private member variables
 	 * Please use the accessor functions instead.
-	 * @private
+	 * @internal
 	 */
 	// @{
 
@@ -143,7 +143,7 @@ class Title implements LinkTarget, IDBAccessObject {
 	 *
 	 * Only public to share cache with TitleFormatter
 	 *
-	 * @private
+	 * @internal
 	 * @var string|null
 	 */
 	public $prefixedText = null;
@@ -1778,7 +1778,7 @@ class Title implements LinkTarget, IDBAccessObject {
 	 * or Title::createFragmentTarget().
 	 * Still in active use privately.
 	 *
-	 * @private
+	 * @internal
 	 * @param string $fragment Text
 	 */
 	public function setFragment( $fragment ) {

includes/WebRequest.php

@@ -419,7 +419,7 @@ class WebRequest {
 	 *
 	 * @param string|array $data
 	 * @return array|string Cleaned-up version of the given
-	 * @private
+	 * @internal
 	 */
 	public function normalizeUnicode( $data ) {
 		if ( is_array( $data ) ) {
@@ -834,7 +834,7 @@ class WebRequest {
 	/**
 	 * Set the session for this request
 	 * @since 1.27
-	 * @private For use by MediaWiki\Session classes only
+	 * @internal For use by MediaWiki\Session classes only
 	 * @param SessionId $sessionId
 	 */
 	public function setSessionId( SessionId $sessionId ) {
@@ -844,7 +844,7 @@ class WebRequest {
 	/**
 	 * Get the session id for this request, if any
 	 * @since 1.27
-	 * @private For use by MediaWiki\Session classes only
+	 * @internal For use by MediaWiki\Session classes only
 	 * @return SessionId|null
 	 */
 	public function getSessionId() {

includes/deferred/AtomicSectionUpdate.php

@@ -41,7 +41,7 @@ class AtomicSectionUpdate implements DeferrableUpdate, DeferrableCallback {
 	}
 
 	/**
-	 * @private This method is public so that it works with onTransactionResolution()
+	 * @internal This method is public so that it works with onTransactionResolution()
 	 * @param int $trigger
 	 */
 	public function cancelOnRollback( $trigger ) {

includes/deferred/AutoCommitUpdate.php

@@ -55,7 +55,7 @@ class AutoCommitUpdate implements DeferrableUpdate, DeferrableCallback {
 	}
 
 	/**
-	 * @private This method is public so that it works with onTransactionResolution()
+	 * @internal This method is public so that it works with onTransactionResolution()
 	 * @param int $trigger
 	 */
 	public function cancelOnRollback( $trigger ) {

includes/deferred/MWCallableUpdate.php

@@ -40,7 +40,7 @@ class MWCallableUpdate
 	}
 
 	/**
-	 * @private This method is public so that it works with onTransactionResolution()
+	 * @internal This method is public so that it works with onTransactionResolution()
 	 * @param int $trigger
 	 */
 	public function cancelOnRollback( $trigger ) {

includes/diff/Diff.php

@@ -26,7 +26,7 @@
 
 /**
  * Class representing a 'diff' between two sequences of strings.
- * @private
+ * @internal
  * @ingroup DifferenceEngine
  */
 class Diff {

includes/diff/DiffOp.php

@@ -31,7 +31,7 @@
  * The classes that extend DiffOp are: DiffOpCopy, DiffOpDelete, DiffOpAdd and
  * DiffOpChange. FakeDiffOp also extends DiffOp, but it is not located in this file.
  *
- * @private
+ * @internal
  * @ingroup DifferenceEngine
  */
 abstract class DiffOp {

includes/diff/DiffOpAdd.php

@@ -29,7 +29,7 @@
  * Extends DiffOp. Used to mark strings that have been
  * added from the first string array.
  *
- * @private
+ * @internal
  * @ingroup DifferenceEngine
  */
 class DiffOpAdd extends DiffOp {

includes/diff/DiffOpChange.php

@@ -29,7 +29,7 @@
  * Extends DiffOp. Used to mark strings that have been
  * changed from the first string array (both added and subtracted).
  *
- * @private
+ * @internal
  * @ingroup DifferenceEngine
  */
 class DiffOpChange extends DiffOp {

includes/diff/DiffOpCopy.php

@@ -29,7 +29,7 @@
  * Extends DiffOp. Used to mark strings that have been
  * copied from one string array to the other.
  *
- * @private
+ * @internal
  * @ingroup DifferenceEngine
  */
 class DiffOpCopy extends DiffOp {

includes/diff/DiffOpDelete.php

@@ -29,7 +29,7 @@
  * Extends DiffOp. Used to mark strings that have been
  * deleted from the first string array.
  *
- * @private
+ * @internal
  * @ingroup DifferenceEngine
  */
 class DiffOpDelete extends DiffOp {

includes/diff/TableDiffFormatter.php

@@ -27,7 +27,7 @@
 /**
  * MediaWiki default table style diff formatter
  * @todo document
- * @private
+ * @internal
  * @ingroup DifferenceEngine
  */
 class TableDiffFormatter extends DiffFormatter {

includes/diff/WordAccumulator.php

@@ -28,7 +28,7 @@ namespace MediaWiki\Diff;
 /**
  * Stores, escapes and formats the results of word-level diff
  *
- * @private
+ * @internal
  * @ingroup DifferenceEngine
  */
 class WordAccumulator {

includes/export/XmlDumpWriter.php

@@ -273,7 +273,7 @@ class XmlDumpWriter {
 	/**
 	 * Closes a "<page>" section on the output stream.
 	 *
-	 * @private
+	 * @internal
 	 * @return string
 	 */
 	public function closePage() {

includes/http/MWCallbackStream.php

@@ -27,7 +27,7 @@ use Psr\Http\Message\StreamInterface;
  * "callback" option, for backward compatibility.  Newer code that uses GuzzleHttpRequest
  * should consider using the "sink" option instead.
  *
- * @private for use by GuzzleHttpRequest only
+ * @internal for use by GuzzleHttpRequest only
  * @since 1.33
  * @property StreamInterface $stream Defined in StreamDecoratorTrait via `@property`, not read
  *  by phan

includes/import/WikiImporter.php

@@ -538,7 +538,7 @@ class WikiImporter {
 	 * Fetches text contents of the current element, assuming
 	 * no sub-elements or such scary things.
 	 * @return string
-	 * @private
+	 * @internal
 	 */
 	public function nodeContents() {
 		if ( $this->reader->isEmptyElement ) {

includes/installer/WebInstallerOutput.php

@@ -33,7 +33,7 @@ use MediaWiki\MediaWikiServices;
  *
  * @ingroup Installer
  * @since 1.17
- * @private
+ * @internal
  */
 class WebInstallerOutput {
 

includes/libs/mime/MimeAnalyzer.php

@@ -1073,7 +1073,7 @@ class MimeAnalyzer implements LoggerAwareInterface {
 	 * distinguish them from MIME types.
 	 *
 	 * This function relies on the mapping defined by $this->mMediaTypes
-	 * @private
+	 * @internal
 	 * @param string $extMime
 	 * @return int|string
 	 */

includes/page/WikiPage.php

@@ -1463,7 +1463,7 @@ class WikiPage implements Page, IDBAccessObject {
 	 * @param null|bool $lastRevIsRedirect If given, will optimize adding and
 	 *   removing rows in redirect table.
 	 * @return bool True on success, false on failure
-	 * @private
+	 * @internal
 	 */
 	public function updateRedirectOn( $dbw, $redirectTitle, $lastRevIsRedirect = null ) {
 		// Always update redirects (target link might have changed)

includes/parser/Parser.php

@@ -535,7 +535,7 @@ class Parser {
 	/**
 	 * Clear Parser state
 	 *
-	 * @private
+	 * @internal
 	 */
 	public function clearState() {
 		$this->firstCallInit();
@@ -1523,7 +1523,7 @@ class Parser {
 	 * Helper function for parse() that transforms wiki markup into half-parsed
 	 * HTML. Only called for $mOutputType == self::OT_HTML.
 	 *
-	 * @private
+	 * @internal
 	 *
 	 * @param string $text The text to parse
 	 * @param-taint $text escapes_html
@@ -1814,7 +1814,7 @@ class Parser {
 	 * @param int $numPostProto
 	 *   The number of characters after the protocol.
 	 * @return string HTML
-	 * @private
+	 * @internal
 	 */
 	private function makeFreeExternalLink( $url, $numPostProto ) {
 		$trail = '';
@@ -2740,7 +2740,7 @@ class Parser {
 	 *
 	 * @param string $text
 	 * @param bool $linestart Whether or not this is at the start of a line.
-	 * @private
+	 * @internal
 	 * @return string The lists rendered as HTML
 	 * @deprecated since 1.35, will not be supported in future parsers
 	 */

includes/parser/Sanitizer.php

@@ -1410,7 +1410,7 @@ class Sanitizer {
 	 *
 	 * @param string $text
 	 * @return string
-	 * @private
+	 * @internal
 	 */
 	public static function normalizeCharReferences( $text ) {
 		return preg_replace_callback(
@@ -1566,7 +1566,7 @@ class Sanitizer {
 	 * character reference, otherwise U+FFFD REPLACEMENT CHARACTER.
 	 * @param int $codepoint
 	 * @return string
-	 * @private
+	 * @internal
 	 */
 	private static function decodeChar( $codepoint ) {
 		if ( self::validateCodepoint( $codepoint ) ) {

includes/session/PHPSessionHandler.php

@@ -151,7 +151,7 @@ class PHPSessionHandler implements \SessionHandlerInterface {
 
 	/**
 	 * Set the manager, store, and logger
-	 * @private Use self::install().
+	 * @internal Use self::install().
 	 * @param SessionManagerInterface $manager
 	 * @param BagOStuff $store
 	 * @param LoggerInterface $logger
@@ -173,7 +173,7 @@ class PHPSessionHandler implements \SessionHandlerInterface {
 
 	/**
 	 * Initialize the session (handler)
-	 * @private For internal use only
+	 * @internal For internal use only
 	 * @param string $save_path Path used to store session files (ignored)
 	 * @param string $session_name Session name (ignored)
 	 * @return true
@@ -190,7 +190,7 @@ class PHPSessionHandler implements \SessionHandlerInterface {
 
 	/**
 	 * Close the session (handler)
-	 * @private For internal use only
+	 * @internal For internal use only
 	 * @return true
 	 */
 	public function close() {
@@ -203,7 +203,7 @@ class PHPSessionHandler implements \SessionHandlerInterface {
 
 	/**
 	 * Read session data
-	 * @private For internal use only
+	 * @internal For internal use only
 	 * @param string $id Session id
 	 * @return string Session data
 	 */
@@ -228,7 +228,7 @@ class PHPSessionHandler implements \SessionHandlerInterface {
 
 	/**
 	 * Write session data
-	 * @private For internal use only
+	 * @internal For internal use only
 	 * @param string $id Session id
 	 * @param string $dataStr Session data. Not that you should ever call this
 	 *   directly, but note that this has the same issues with code injection
@@ -337,7 +337,7 @@ class PHPSessionHandler implements \SessionHandlerInterface {
 
 	/**
 	 * Destroy a session
-	 * @private For internal use only
+	 * @internal For internal use only
 	 * @param string $id Session id
 	 * @return true
 	 */
@@ -357,7 +357,7 @@ class PHPSessionHandler implements \SessionHandlerInterface {
 
 	/**
 	 * Execute garbage collection.
-	 * @private For internal use only
+	 * @internal For internal use only
 	 * @param int $maxlifetime Maximum session life time (ignored)
 	 * @return true
 	 * @codeCoverageIgnore See T135576

includes/session/Session.php

@@ -83,7 +83,7 @@ class Session implements \Countable, \Iterator, \ArrayAccess {
 
 	/**
 	 * Returns the SessionId object
-	 * @private For internal use by WebRequest
+	 * @internal For internal use by WebRequest
 	 * @return SessionId
 	 */
 	public function getSessionId() {

includes/session/SessionBackend.php

@@ -206,7 +206,7 @@ final class SessionBackend {
 
 	/**
 	 * Deregister a Session
-	 * @private For use by \MediaWiki\Session\Session::__destruct() only
+	 * @internal For use by \MediaWiki\Session\Session::__destruct() only
 	 * @param int $index
 	 */
 	public function deregisterSession( $index ) {
@@ -219,7 +219,7 @@ final class SessionBackend {
 
 	/**
 	 * Shut down a session
-	 * @private For use by \MediaWiki\Session\SessionManager::shutdown() only
+	 * @internal For use by \MediaWiki\Session\SessionManager::shutdown() only
 	 */
 	public function shutdown() {
 		$this->save( true );
@@ -236,7 +236,7 @@ final class SessionBackend {
 
 	/**
 	 * Fetch the SessionId object
-	 * @private For internal use by WebRequest
+	 * @internal For internal use by WebRequest
 	 * @return SessionId
 	 */
 	public function getSessionId() {
@@ -539,7 +539,7 @@ final class SessionBackend {
 	 * Note the caller is responsible for calling $this->dirty() if anything in
 	 * the array is changed.
 	 *
-	 * @private For use by \MediaWiki\Session\Session only.
+	 * @internal For use by \MediaWiki\Session\Session only.
 	 * @return array
 	 */
 	public function &getData() {
@@ -571,7 +571,7 @@ final class SessionBackend {
 
 	/**
 	 * Mark data as dirty
-	 * @private For use by \MediaWiki\Session\Session only.
+	 * @internal For use by \MediaWiki\Session\Session only.
 	 */
 	public function dirty() {
 		$this->dataDirty = true;

includes/session/SessionId.php

@@ -56,7 +56,7 @@ final class SessionId {
 
 	/**
 	 * Set the ID
-	 * @private For use by \MediaWiki\Session\SessionManager only
+	 * @internal For use by \MediaWiki\Session\SessionManager only
 	 * @param string $id
 	 */
 	public function setId( $id ) {

includes/session/SessionManager.php

@@ -401,7 +401,7 @@ final class SessionManager implements SessionManagerInterface {
 	 * The intention is that the named account will never again be usable for
 	 * normal login (i.e. there is no way to undo the prevention of access).
 	 *
-	 * @private For use from \User::newSystemUser only
+	 * @internal For use from \User::newSystemUser only
 	 * @param string $username
 	 */
 	public function preventSessionsForUser( $username ) {
@@ -415,7 +415,7 @@ final class SessionManager implements SessionManagerInterface {
 
 	/**
 	 * Test if a user is prevented
-	 * @private For use from SessionBackend only
+	 * @internal For use from SessionBackend only
 	 * @param string $username
 	 * @return bool
 	 */
@@ -464,7 +464,7 @@ final class SessionManager implements SessionManagerInterface {
 
 	/**
 	 * Save all active sessions on shutdown
-	 * @private For internal use with register_shutdown_function()
+	 * @internal For internal use with register_shutdown_function()
 	 */
 	public function shutdown() {
 		if ( $this->allSessionBackends ) {
@@ -832,7 +832,7 @@ final class SessionManager implements SessionManagerInterface {
 
 	/**
 	 * Create a Session corresponding to the passed SessionInfo
-	 * @private For use by a SessionProvider that needs to specially create its
+	 * @internal For use by a SessionProvider that needs to specially create its
 	 *  own Session. Most session providers won't need this.
 	 * @param SessionInfo $info
 	 * @param WebRequest $request
@@ -893,7 +893,7 @@ final class SessionManager implements SessionManagerInterface {
 
 	/**
 	 * Deregister a SessionBackend
-	 * @private For use from \MediaWiki\Session\SessionBackend only
+	 * @internal For use from \MediaWiki\Session\SessionBackend only
 	 * @param SessionBackend $backend
 	 */
 	public function deregisterSessionBackend( SessionBackend $backend ) {
@@ -911,7 +911,7 @@ final class SessionManager implements SessionManagerInterface {
 
 	/**
 	 * Change a SessionBackend's ID
-	 * @private For use from \MediaWiki\Session\SessionBackend only
+	 * @internal For use from \MediaWiki\Session\SessionBackend only
 	 * @param SessionBackend $backend
 	 */
 	public function changeBackendId( SessionBackend $backend ) {
@@ -946,7 +946,7 @@ final class SessionManager implements SessionManagerInterface {
 
 	/**
 	 * Call setters on a PHPSessionHandler
-	 * @private Use PhpSessionHandler::install()
+	 * @internal Use PhpSessionHandler::install()
 	 * @param PHPSessionHandler $handler
 	 */
 	public function setupPHPSessionHandler( PHPSessionHandler $handler ) {

includes/skins/Skin.php

@@ -1114,7 +1114,7 @@ abstract class Skin extends ContextSource {
 	 * This may include an 'oldid' specifier, if the current page view is such.
 	 *
 	 * @return array
-	 * @private
+	 * @internal
 	 */
 	public function editUrlOptions() {
 		$options = [ 'action' => 'edit' ];

includes/specialpage/AuthManagerSpecialPage.php

@@ -475,7 +475,7 @@ abstract class AuthManagerSpecialPage extends SpecialPage {
 
 	/**
 	 * Submit handler callback for HTMLForm
-	 * @private
+	 * @internal
 	 * @param array $data Submitted data
 	 * @return Status
 	 */

includes/specialpage/LoginSignupSpecialPage.php

@@ -117,7 +117,7 @@ abstract class LoginSignupSpecialPage extends AuthManagerSpecialPage {
 
 	/**
 	 * Load data from request.
-	 * @private
+	 * @internal
 	 * @param string $subPage Subpage of Special:Userlogin
 	 */
 	protected function load( $subPage ) {
@@ -513,7 +513,7 @@ abstract class LoginSignupSpecialPage extends AuthManagerSpecialPage {
 	 * @throws MWException
 	 * @throws PermissionsError
 	 * @throws ReadOnlyError
-	 * @private
+	 * @internal
 	 */
 	protected function mainLoginForm( array $requests, $msg = '', $msgtype = 'error' ) {
 		$user = $this->getUser();

includes/specials/SpecialProtectedtitles.php

@@ -111,7 +111,7 @@ class SpecialProtectedtitles extends SpecialPage {
 	 * @param string $type
 	 * @param string $level
 	 * @return string
-	 * @private
+	 * @internal
 	 */
 	private function showOptions( $namespace, $type, $level ) {
 		$formDescriptor = [
@@ -138,7 +138,7 @@ class SpecialProtectedtitles extends SpecialPage {
 	/**
 	 * @param string $pr_level Determines which option is selected as default
 	 * @return string|array
-	 * @private
+	 * @internal
 	 */
 	private function getLevelMenu( $pr_level ) {
 		// Temporary array

includes/specials/formfields/Licenses.php

@@ -88,7 +88,7 @@ class Licenses extends HTMLFormField {
 	}
 
 	/**
-	 * @private
+	 * @internal
 	 */
 	protected function makeLines() {
 		$levels = [];

includes/title/TitleValue.php

@@ -65,7 +65,7 @@ class TitleValue implements LinkTarget {
 	 *
 	 * Only public to share cache with TitleFormatter
 	 *
-	 * @private
+	 * @internal
 	 * @var string
 	 */
 	public $prefixedText = null;