Improve function and property documentation by using class-string type
class-string type allows static code analyzer to determine class strings
When explicit class is known, use generic type to specify
Change-Id: I602b4bfad924bf1f3eadbeaae7199ff7e04d441f
diff --git a/includes/AutoLoader.php b/includes/AutoLoader.php
index b9d905a..101b367 100644
--- a/includes/AutoLoader.php
+++ b/includes/AutoLoader.php
@@ -210,7 +210,7 @@
/**
* Find the file containing the given class.
*
- * @param string $className Name of class we're looking for.
+ * @param class-string $className Name of class we're looking for.
* @return string|null The path containing the class, not null if not found
*/
public static function find( $className ): ?string {
@@ -265,7 +265,7 @@
/**
* autoload - take a class name and attempt to load it
*
- * @param string $className Name of class we're looking for.
+ * @param class-string $className Name of class we're looking for.
*/
public static function autoload( $className ) {
$filename = self::find( $className );
diff --git a/includes/Settings/Source/JsonSchemaTrait.php b/includes/Settings/Source/JsonSchemaTrait.php
index ef3dd05..80f9891 100644
--- a/includes/Settings/Source/JsonSchemaTrait.php
+++ b/includes/Settings/Source/JsonSchemaTrait.php
@@ -108,7 +108,7 @@
*
* @param array $schema JSON Schema structure with PHPDoc types
* @param array &$defs List of definitions (JSON schemas) referenced in the schema
- * @param string $source An identifier for the source schema being reflected, used
+ * @param class-string $source An identifier for the source schema being reflected, used
* for error descriptions.
* @param string $propertyName The name of the property the schema belongs to, used for error descriptions.
* @return array JSON Schema structure using only proper JSON types
@@ -131,7 +131,7 @@
*
* @param array $schema JSON Schema structure with PHPDoc types
* @param array &$defs List of definitions (JSON schemas) referenced in the schema
- * @param string $source An identifier for the source schema being reflected, used
+ * @param class-string $source An identifier for the source schema being reflected, used
* for error descriptions.
* @param string $propertyName The name of the property the schema belongs to, used for error descriptions.
* @param bool $inlineReferences Whether references in the schema should be inlined or not.
diff --git a/includes/Settings/Source/ReflectionSchemaSource.php b/includes/Settings/Source/ReflectionSchemaSource.php
index d1c8803..463df5f 100644
--- a/includes/Settings/Source/ReflectionSchemaSource.php
+++ b/includes/Settings/Source/ReflectionSchemaSource.php
@@ -40,7 +40,7 @@
/**
* Name of a PHP class
- * @var string
+ * @var class-string
*/
private $class;
@@ -50,7 +50,7 @@
private $includeDoc;
/**
- * @param string $class
+ * @param class-string $class
* @param bool $includeDoc
*/
public function __construct( string $class, bool $includeDoc = false ) {
diff --git a/includes/auth/AuthManager.php b/includes/auth/AuthManager.php
index 071229a..3a7ae31 100644
--- a/includes/auth/AuthManager.php
+++ b/includes/auth/AuthManager.php
@@ -2810,7 +2810,7 @@
/**
* Create an array of AuthenticationProviders from an array of ObjectFactory specs
- * @param string $class
+ * @param class-string<AuthenticationProvider> $class
* @param array[] $specs
* @return AuthenticationProvider[]
*/
diff --git a/includes/auth/AuthenticationRequest.php b/includes/auth/AuthenticationRequest.php
index 6b62c33..103d2ac 100644
--- a/includes/auth/AuthenticationRequest.php
+++ b/includes/auth/AuthenticationRequest.php
@@ -292,7 +292,7 @@
*
* @phan-template T
* @param AuthenticationRequest[] $reqs
- * @param string $class Class name
+ * @param class-string<AuthenticationRequest> $class Class name
* @phan-param class-string<T> $class
* @param bool $allowSubclasses If true, also returns any request that's a subclass of the given
* class.
diff --git a/includes/content/VueContentHandler.php b/includes/content/VueContentHandler.php
index 25a513c..768df36 100644
--- a/includes/content/VueContentHandler.php
+++ b/includes/content/VueContentHandler.php
@@ -54,7 +54,7 @@
}
/**
- * @return string
+ * @return class-string<VueContent>
*/
protected function getContentClass() {
return VueContent::class;
diff --git a/includes/db/MWLBFactory.php b/includes/db/MWLBFactory.php
index 6c9e368..efb75e5 100644
--- a/includes/db/MWLBFactory.php
+++ b/includes/db/MWLBFactory.php
@@ -36,6 +36,7 @@
use Wikimedia\Rdbms\ConfiguredReadOnlyMode;
use Wikimedia\Rdbms\DatabaseDomain;
use Wikimedia\Rdbms\ILBFactory;
+use Wikimedia\Rdbms\LBFactory;
use Wikimedia\RequestTimeout\CriticalSectionProvider;
use Wikimedia\Stats\StatsFactory;
use Wikimedia\Telemetry\TracerInterface;
@@ -367,7 +368,7 @@
*
* @internal For use by ServiceWiring
* @param array $config (e.g. $wgLBFactoryConf)
- * @return string Class name
+ * @return class-string<LBFactory>
*/
public function getLBFactoryClass( array $config ): string {
$compat = [
diff --git a/includes/debug/DeprecationHelper.php b/includes/debug/DeprecationHelper.php
index 099cbe4..fba9fd3 100644
--- a/includes/debug/DeprecationHelper.php
+++ b/includes/debug/DeprecationHelper.php
@@ -159,7 +159,7 @@
* are accessed.
*
* @param string $version MediaWiki version where the property became deprecated.
- * @param string|null $class The class which has the deprecated property.
+ * @param class-string|null $class The class which has the deprecated property.
* @param string|null $component
*/
protected function deprecateDynamicPropertiesAccess(
diff --git a/includes/debug/MWDebug.php b/includes/debug/MWDebug.php
index 790c79a..f587ae3 100644
--- a/includes/debug/MWDebug.php
+++ b/includes/debug/MWDebug.php
@@ -246,7 +246,7 @@
*
* @phpcs:ignore MediaWiki.Commenting.FunctionComment.ObjectTypeHintParam
* @param object $instance Object on which to detect deprecated overrides (typically $this).
- * @param string $class Class declaring the deprecated method (typically __CLASS__ )
+ * @param class-string $class Class declaring the deprecated method (typically __CLASS__ )
* @param string $method The name of the deprecated method.
* @param string|false $version Version in which the method was deprecated.
* Does not issue deprecation warnings if false.
diff --git a/includes/filebackend/lockmanager/LockManagerGroup.php b/includes/filebackend/lockmanager/LockManagerGroup.php
index e886673..ce577d9 100644
--- a/includes/filebackend/lockmanager/LockManagerGroup.php
+++ b/includes/filebackend/lockmanager/LockManagerGroup.php
@@ -77,7 +77,7 @@
// Lazy-load the actual lock manager instance
if ( !isset( $this->managers[$name]['instance'] ) ) {
$class = $this->managers[$name]['class'];
- '@phan-var string $class';
+ '@phan-var class-string<LockManager> $class';
$config = $this->managers[$name]['config'];
$config['logger'] = LoggerFactory::getInstance( 'LockManager' );
diff --git a/includes/gallery/ImageGalleryBase.php b/includes/gallery/ImageGalleryBase.php
index edba06f..b53c304 100644
--- a/includes/gallery/ImageGalleryBase.php
+++ b/includes/gallery/ImageGalleryBase.php
@@ -110,7 +110,7 @@
/** @var int */
protected $mHeights;
- /** @var array */
+ /** @var array<string,class-string<self>> */
private static $modeMapping;
/**
diff --git a/includes/htmlform/HTMLForm.php b/includes/htmlform/HTMLForm.php
index 7bec921..0005ce3 100644
--- a/includes/htmlform/HTMLForm.php
+++ b/includes/htmlform/HTMLForm.php
@@ -600,7 +600,7 @@
* @param array &$descriptor Input Descriptor, as described
* in the class documentation
*
- * @return string Name of a HTMLFormField subclass
+ * @return class-string<HTMLFormField> Name of a HTMLFormField subclass
*/
public static function getClassFromDescriptor( $fieldname, &$descriptor ) {
if ( isset( $descriptor['class'] ) ) {
diff --git a/includes/installer/DatabaseUpdater.php b/includes/installer/DatabaseUpdater.php
index 97fbfd3..0aced11 100644
--- a/includes/installer/DatabaseUpdater.php
+++ b/includes/installer/DatabaseUpdater.php
@@ -97,7 +97,7 @@
protected $autoExtensionHookContainer;
/**
- * @var string[] Scripts to run after database update
+ * @var class-string<Maintenance>[] Scripts to run after database update
* Should be a subclass of LoggedUpdateMaintenance
*/
protected $postDatabaseUpdateMaintenance = [
@@ -432,7 +432,7 @@
*
* @since 1.19
*
- * @param string $class Name of a Maintenance subclass
+ * @param class-string<Maintenance> $class Name of a Maintenance subclass
*/
public function addPostDatabaseUpdateMaintenance( $class ) {
$this->postDatabaseUpdateMaintenance[] = $class;
@@ -441,7 +441,7 @@
/**
* @since 1.17
*
- * @return string[]
+ * @return class-string<Maintenance>[]
*/
public function getPostDatabaseUpdateMaintenance() {
return $this->postDatabaseUpdateMaintenance;
diff --git a/includes/installer/Installer.php b/includes/installer/Installer.php
index a699dfa..879b15d 100644
--- a/includes/installer/Installer.php
+++ b/includes/installer/Installer.php
@@ -91,14 +91,14 @@
/**
* List of detected DBs, access using getCompiledDBs().
*
- * @var array
+ * @var string[]
*/
protected $compiledDBs;
/**
* Cached DB installer instances, access using getDBInstaller().
*
- * @var array
+ * @var array<string,DatabaseInstaller>
*/
protected $dbInstallers = [];
@@ -621,7 +621,7 @@
/**
* Get a list of DBs supported by current PHP setup
*
- * @return array
+ * @return string[]
*/
public function getCompiledDBs() {
return $this->compiledDBs;
@@ -631,7 +631,7 @@
* Get the DatabaseInstaller class name for this type
*
* @param string $type database type ($wgDBtype)
- * @return string Class name
+ * @return class-string<DatabaseInstaller> Class name
* @since 1.30
*/
public static function getDBInstallerClass( $type ) {
@@ -641,7 +641,7 @@
/**
* Get an instance of DatabaseInstaller for the specified DB type.
*
- * @param mixed $type DB installer for which is needed, false to use default.
+ * @param string|false $type DB installer for which is needed, false to use default.
*
* @return DatabaseInstaller
*/
diff --git a/includes/installer/InstallerOverrides.php b/includes/installer/InstallerOverrides.php
index eadbe7d..e12479f 100644
--- a/includes/installer/InstallerOverrides.php
+++ b/includes/installer/InstallerOverrides.php
@@ -29,6 +29,7 @@
* @since 1.20
*/
class InstallerOverrides {
+ /** @return array<string,class-string> */
private static function getOverrides(): array {
static $overrides;
diff --git a/includes/language/LanguageFactory.php b/includes/language/LanguageFactory.php
index 2218b69..3fd926a 100644
--- a/includes/language/LanguageFactory.php
+++ b/includes/language/LanguageFactory.php
@@ -229,7 +229,7 @@
/**
* @param string $code
* @param bool $fallback Whether we're going through the language fallback chain
- * @return string Name of the language class
+ * @return class-string<Language> Name of the language class
*/
private function classFromCode( $code, $fallback = true ) {
if ( $fallback && $code == 'en' ) {
diff --git a/includes/libs/Stats/StatsFactory.php b/includes/libs/Stats/StatsFactory.php
index dc206e1..3bf1e23 100644
--- a/includes/libs/Stats/StatsFactory.php
+++ b/includes/libs/Stats/StatsFactory.php
@@ -190,7 +190,7 @@
* If a metric name collision occurs, returns a NullMetric to suppress runtime exceptions.
*
* @param string $name
- * @param string $className
+ * @param class-string $className
* @return CounterMetric|TimingMetric|GaugeMetric|NullMetric
*/
private function getMetric( string $name, string $className ) {
diff --git a/includes/libs/rdbms/database/DatabaseFactory.php b/includes/libs/rdbms/database/DatabaseFactory.php
index 32bf9d2..a049399 100644
--- a/includes/libs/rdbms/database/DatabaseFactory.php
+++ b/includes/libs/rdbms/database/DatabaseFactory.php
@@ -194,7 +194,7 @@
/**
* @param string $dbType A possible DB type (sqlite, mysql, postgres,...)
* @param string|null $driver Optional name of a specific DB client driver
- * @return string Database subclass name to use
+ * @return class-string<Database> Database subclass name to use
* @throws InvalidArgumentException
*/
protected function getClass( $dbType, $driver = null ) {
diff --git a/includes/objectcache/ObjectCacheFactory.php b/includes/objectcache/ObjectCacheFactory.php
index 9b0a070..d973066 100644
--- a/includes/objectcache/ObjectCacheFactory.php
+++ b/includes/objectcache/ObjectCacheFactory.php
@@ -98,7 +98,7 @@
private $dbLoadBalancerFactory;
/**
* @internal ObjectCacheFactoryTest only
- * @var string
+ * @var class-string<BagOStuff>
*/
public static $localServerCacheClass;
@@ -328,7 +328,7 @@
/**
* Get the class which will be used for the local server cache
- * @return string
+ * @return class-string<BagOStuff>
*/
private static function getLocalServerCacheClass() {
if ( self::$localServerCacheClass !== null ) {
diff --git a/includes/page/CategoryPage.php b/includes/page/CategoryPage.php
index 12fbf71..76dca55 100644
--- a/includes/page/CategoryPage.php
+++ b/includes/page/CategoryPage.php
@@ -31,7 +31,7 @@
* @method WikiCategoryPage getPage() Set by overwritten newPage() in this class
*/
class CategoryPage extends Article {
- /** @var string Subclasses can change this to override the viewer class. */
+ /** @var class-string<CategoryViewer> Subclasses can change this to override the viewer class. */
protected $mCategoryViewerClass = CategoryViewer::class;
/**
diff --git a/includes/parser/PPDStackElement_Hash.php b/includes/parser/PPDStackElement_Hash.php
index 668f737..9db25fa 100644
--- a/includes/parser/PPDStackElement_Hash.php
+++ b/includes/parser/PPDStackElement_Hash.php
@@ -66,7 +66,7 @@
*/
public $lineStart;
- /** @var string */
+ /** @var class-string<PPDPart_Hash> */
public $partClass = PPDPart_Hash::class;
public function __construct( array $data = [] ) {
diff --git a/includes/parser/PPDStack_Hash.php b/includes/parser/PPDStack_Hash.php
index e879b8f..39d8cdb 100644
--- a/includes/parser/PPDStack_Hash.php
+++ b/includes/parser/PPDStack_Hash.php
@@ -42,7 +42,7 @@
public $top;
/** @var string|null */
public $out;
- /** @var string */
+ /** @var class-string<PPDStackElement_Hash> */
public $elementClass = PPDStackElement_Hash::class;
public function __construct() {
diff --git a/includes/preferences/DefaultPreferencesFactory.php b/includes/preferences/DefaultPreferencesFactory.php
index dfa6f46..3e8d519 100644
--- a/includes/preferences/DefaultPreferencesFactory.php
+++ b/includes/preferences/DefaultPreferencesFactory.php
@@ -1931,7 +1931,7 @@
/**
* @param User $user
* @param IContextSource $context
- * @param string $formClass
+ * @param class-string<PreferencesFormOOUI> $formClass
* @param array $remove Array of items to remove
* @return HTMLForm
*/
diff --git a/includes/skins/SkinTemplate.php b/includes/skins/SkinTemplate.php
index adfa467..82fc22c 100644
--- a/includes/skins/SkinTemplate.php
+++ b/includes/skins/SkinTemplate.php
@@ -91,7 +91,7 @@
* and eventually it spits out some HTML. Should have interface
* roughly equivalent to PHPTAL 0.7.
*
- * @param string $classname
+ * @param class-string<QuickTemplate> $classname
* @return QuickTemplate
*/
protected function setupTemplate( $classname ) {
diff --git a/includes/specialpage/Hook/WgQueryPagesHook.php b/includes/specialpage/Hook/WgQueryPagesHook.php
index f185800..38a6450 100644
--- a/includes/specialpage/Hook/WgQueryPagesHook.php
+++ b/includes/specialpage/Hook/WgQueryPagesHook.php
@@ -17,7 +17,7 @@
* @since 1.35
*
* @param array[] &$qp List of QueryPages
- * Format: [ string $class, string $specialPageName, ?int $limit (optional) ].
+ * Format: [ class-string $class, string $specialPageName, ?int $limit (optional) ].
* Limit defaults to $wgQueryCacheLimit if not given.
* @return bool|void True or no return value to continue or false to abort
*/
diff --git a/includes/specialpage/QueryPage.php b/includes/specialpage/QueryPage.php
index 75c1af5..ab7df13 100644
--- a/includes/specialpage/QueryPage.php
+++ b/includes/specialpage/QueryPage.php
@@ -129,7 +129,7 @@
* When changing this list, you should ensure that maintenance/updateSpecialPages.php still works
* including when test data exists.
*
- * @return array[] List of [ string $class, string $specialPageName, ?int $limit (optional) ].
+ * @return array[] List of [ class-string $class, string $specialPageName, ?int $limit (optional) ].
* Limit defaults to $wgQueryCacheLimit if not given.
*/
public static function getPages() {
diff --git a/maintenance/includes/BackupDumper.php b/maintenance/includes/BackupDumper.php
index ffdf1ed..07a8da6 100644
--- a/maintenance/includes/BackupDumper.php
+++ b/maintenance/includes/BackupDumper.php
@@ -32,6 +32,7 @@
require_once __DIR__ . '/../../includes/export/WikiExporter.php';
// @codeCoverageIgnoreEnd
+use DumpFilter;
use DumpMultiWriter;
use DumpOutput;
use ExportProgressFilter;
@@ -92,9 +93,9 @@
/** @var int */
protected $revCountLast = 0;
- /** @var string[] */
+ /** @var array<string,class-string<DumpOutput>> */
protected $outputTypes = [];
- /** @var string[] */
+ /** @var array<string,class-string<DumpFilter>> */
protected $filterTypes = [];
/** @var int */
@@ -190,7 +191,7 @@
/**
* @param string $name
- * @param string $class Name of output filter plugin class
+ * @param class-string<DumpOutput> $class Name of output filter plugin class
*/
public function registerOutput( $name, $class ) {
$this->outputTypes[$name] = $class;
@@ -198,7 +199,7 @@
/**
* @param string $name
- * @param string $class Name of filter plugin class
+ * @param class-string<DumpFilter> $class Name of filter plugin class
*/
public function registerFilter( $name, $class ) {
$this->filterTypes[$name] = $class;
@@ -207,7 +208,7 @@
/**
* Load a plugin and register it
*
- * @param string $class Name of plugin class; must have a static 'register'
+ * @param class-string $class Name of plugin class; must have a static 'register'
* method that takes a BackupDumper as a parameter.
* @param string $file Full or relative path to the PHP file to load, or empty
*/
diff --git a/maintenance/includes/Maintenance.php b/maintenance/includes/Maintenance.php
index 23126ab..410f966 100644
--- a/maintenance/includes/Maintenance.php
+++ b/maintenance/includes/Maintenance.php
@@ -758,7 +758,7 @@
*
* Callers are expected to run the returned maintenance script instance by calling {@link Maintenance::execute}
*
- * @param string $maintClass A name of a child maintenance class
+ * @param class-string<Maintenance> $maintClass A name of a child maintenance class
* @param string|null $classFile Full path of where the child is
* @stable to override
* @return Maintenance The created instance, which the caller is expected to run by calling
diff --git a/maintenance/storage/recompressTracked.php b/maintenance/storage/recompressTracked.php
index d0a2f0b..ae012fe 100644
--- a/maintenance/storage/recompressTracked.php
+++ b/maintenance/storage/recompressTracked.php
@@ -71,9 +71,9 @@
public $numProcs = 1;
/** @var int */
public $numBatches = 0;
- /** @var string */
+ /** @var class-string<HistoryBlob> */
public $pageBlobClass;
- /** @var string */
+ /** @var class-string<HistoryBlob> */
public $orphanBlobClass;
/** @var resource[] */
public $childPipes;
@@ -709,7 +709,7 @@
class CgzCopyTransaction {
/** @var RecompressTracked */
public $parent;
- /** @var string */
+ /** @var class-string<HistoryBlob> */
public $blobClass;
/** @var ConcatenatedGzipHistoryBlob|false */
public $cgz;
@@ -721,7 +721,7 @@
/**
* Create a transaction from a RecompressTracked object
* @param RecompressTracked $parent
- * @param string $blobClass
+ * @param class-string<HistoryBlob> $blobClass
*/
public function __construct( $parent, $blobClass ) {
$this->blobClass = $blobClass;