Many small fixes to incomplete/unspecific/broken PHPDoc comments

E.g. adding missing types or fixing inconsistencies. This patch is
exclusively about comments and should be fairly easy to review, I
hope. It should be impossible such a patch can break anything.

Mistakes like this happen because the relevant MediaWiki CodeSniffer
sniff is disabled in this codebase. I would love to enable it at
least partially, if possible. This is done in preparation.

Change-Id: Ie6a676df1ac88eb65d1cb1b923e29d0e20d893e2

client/includes/ClientHooks.php

@@ -2,6 +2,7 @@
 
 namespace Wikibase\Client;
 
+use CirrusSearch\SearchConfig;
 use MediaWiki\MediaWikiServices;
 use MediaWiki\Title\Title;
 use Skin;
@@ -165,7 +166,7 @@ public static function onGetDoubleUnderscoreIDs( &$doubleUnderscoreIDs ) {
 
 	/**
 	 * Add morelikewithwikibase keyword.
-	 * @param $config
+	 * @param SearchConfig $config
 	 * @param array &$extraFeatures
 	 */
 	public static function onCirrusSearchAddQueryFeatures(
@@ -260,7 +261,7 @@ function () {
 		);
 	}
 
-	/** @param ContentLanguages[] $contentLanguages */
+	/** @param ContentLanguages[] &$contentLanguages */
 	public static function onWikibaseContentLanguages( array &$contentLanguages ): void {
 		if ( !WikibaseClient::getSettings()->getSetting( 'tmpEnableMulLanguageCode' ) ) {
 			return;

client/includes/DataAccess/ParserFunctions/Runner.php

@@ -4,6 +4,7 @@
 
 use Parser;
 use PPFrame;
+use PPNode;
 use Wikibase\Client\DataAccess\DataAccessSnakFormatterFactory;
 use Wikibase\Client\WikibaseClient;
 use Wikibase\DataModel\Entity\EntityId;
@@ -76,7 +77,7 @@ public function __construct(
 	/**
 	 * @param Parser $parser
 	 * @param PPFrame $frame
-	 * @param array $args
+	 * @param PPNode[] $args
 	 * @param string $type One of DataAccessSnakFormatterFactory::TYPE_*
 	 *
 	 * @return array Wikitext in element 0, flags in named elements

client/includes/DataAccess/Scribunto/CachingFallbackBasedTermLookup.php

@@ -170,7 +170,7 @@ private function getLookup( Language $language ): LanguageFallbackLabelDescripti
 	/**
 	 * @param EntityId $entityId
 	 * @param Language $language
-	 * @param $termType
+	 * @param string $termType
 	 * @return TermFallback|null
 	 */
 	private function lookupWithoutCache( EntityId $entityId, Language $language, $termType ): ?TermFallback {

client/includes/DataAccess/Scribunto/EntityAccessor.php

@@ -251,7 +251,7 @@ private function newClientStatementListSerializer() {
 
 	/**
 	 * @see UnresolvedEntityRedirectException
-	 * @param $prefixedEntityId
+	 * @param string $prefixedEntityId
 	 */
 	private function logPossibleDoubleRedirect( $prefixedEntityId ) {
 		$this->logger->info( 'Unresolved redirect encountered loading {prefixedEntityId}. This is typically cleaned up asynchronously.',

client/includes/Hooks/ChangesListLinesHandler.php

@@ -72,7 +72,7 @@ public static function factory(
 	}
 
 	/**
-	 * @param OldChangesList &$changesList
+	 * @param OldChangesList $changesList
 	 * @param string &$s
 	 * @param RecentChange $rc
 	 * @param string[] &$classes

client/includes/Hooks/SkinAfterPortletHandler.php

@@ -50,7 +50,7 @@ public static function factory(
 	/**
 	 * @param Skin $skin
 	 * @param string $portlet
-	 * @param string $html
+	 * @param string &$html
 	 */
 	public function onSkinAfterPortlet( $skin, $portlet, &$html ): void {
 		if ( $portlet === 'lang' ) {

client/includes/Hooks/TrivialHookHandler.php

@@ -99,7 +99,7 @@ public function onSearchDataForIndex2(
 	}
 
 	/**
-	 * @param array $fields
+	 * @param array &$fields
 	 * @param ParserOutput $parserOutput
 	 */
 	private function doSearchDataForIndex( array &$fields, ParserOutput $parserOutput ): void {

client/includes/Hooks/WikibaseClientHookRunner.php

@@ -3,6 +3,7 @@
 namespace Wikibase\Client\Hooks;
 
 use MediaWiki\HookContainer\HookContainer;
+use Wikibase\Lib\Changes\EntityChange;
 
 /**
  * Handle Changes' hooks
@@ -24,7 +25,7 @@ public function __construct( HookContainer $hookContainer ) {
 	/**
 	 * Hook runner for the 'WikibaseHandleChange' hook
 	 *
-	 * @param $change
+	 * @param EntityChange $change
 	 * @param array $rootJobParams
 	 * @return bool
 	 */

client/includes/Hooks/WikibaseHandleChangeHook.php

@@ -2,6 +2,8 @@
 
 namespace Wikibase\Client\Hooks;
 
+use Wikibase\Lib\Changes\EntityChange;
+
 /**
  * @license GPL-2.0-or-later
  */
@@ -10,7 +12,7 @@ interface WikibaseHandleChangeHook {
 	/**
 	 * Hook runner for the 'WikibaseHandleChange' hook
 	 *
-	 * @param $change
+	 * @param EntityChange $change
 	 * @param array $rootJobParams
 	 * @return bool
 	 */

client/includes/Store/DescriptionLookup.php

@@ -64,7 +64,7 @@ public function __construct(
 	 * @param Title[] $titles Titles to look up (will be loaded).
 	 * @param array|string $sources One or both of the DescriptionLookup::SOURCE_* constants.
 	 *   When an array is provided, the second element will be used as fallback.
-	 * @param null $actualSources Will be set to an associative array of page ID => SOURCE_*,
+	 * @param array|null &$actualSources Will be set to an associative array of page ID => SOURCE_*,
 	 *   indicating where each description came from, or null if no description was found.
 	 * @return string[] Associative array of page ID => description. Pages with no description
 	 *   will be omitted.
@@ -102,7 +102,7 @@ public function getDescriptions( array $titles, $sources, &$actualSources = null
 	 * @param Title $title Title to look up (will be loaded).
 	 * @param array|string $sources One or both of the DescriptionLookup::SOURCE_* constants.
 	 *   When an array is provided, the second element will be used as fallback.
-	 * @param null $actualSource Will be set to one of the DescriptionLookup::SOURCE_* constants,
+	 * @param string|null &$actualSource Will be set to one of the DescriptionLookup::SOURCE_* constants,
 	 *   indicating where the description came from, or null if no description was found.
 	 * @return string|null The description, or null if none was found.
 	 */

client/tests/phpunit/unit/includes/DataAccess/ParserFunctions/LanguageAwareRendererTest.php

@@ -76,7 +76,7 @@ private function getRenderer(
 
 	/**
 	 * Return a mock ParserOutput object that checks how many times it adds a tracking category.
-	 * @param $num Number of times a tracking category should be added
+	 * @param int $num Number of times a tracking category should be added
 	 *
 	 * @return ParserOutput
 	 */

client/tests/phpunit/unit/includes/Hooks/ExtensionLoadHandlerTest.php

@@ -20,7 +20,7 @@
 class ExtensionLoadHandlerTest extends TestCase {
 
 	/**
-	 * @param &$hooks
+	 * @param array &$hooks
 	 *
 	 * @return MockObject&HookContainer
 	 */

data-access/src/DatabaseEntitySource.php

@@ -56,7 +56,7 @@ class DatabaseEntitySource implements EntitySource {
 	 * @param string $name Unique name for the source for a given configuration / site, used for indexing the sources internally.
 	 *        This does not have to be a wikiname, sitename or dbname, it can for example just be 'properties'.
 	 * @param string|false $databaseName The name of the database to use (use false for the local db)
-	 * @param array $entityNamespaceIdsAndSlots Associative array indexed by entity type (string), values are
+	 * @param array<string,array> $entityNamespaceIdsAndSlots Associative array indexed by entity type (string), values are
 	 * array of form [ 'namespaceId' => int, 'slot' => string ]
 	 * @param string $conceptBaseUri
 	 * @param string $rdfNodeNamespacePrefix

data-access/tests/phpunit/InMemoryPrefetchingTermLookup.php

@@ -49,8 +49,8 @@ public function setData( array $entityData ) {
 
 	/**
 	 * @param array $entityIds
-	 * @param array $termTypes if null, defaults to labels and descriptions only
-	 * @param array $languageCodes if null, defaults to nothing
+	 * @param array|null $termTypes if null, defaults to labels and descriptions only
+	 * @param array|null $languageCodes if null, defaults to nothing
 	 * @note These defaults do not strictly obey the definitions of the interface
 	 * but instead are similar to the FakePrefetchingTermLookup
 	 */

lib/includes/Modules/SitesModuleBase.php

@@ -58,6 +58,7 @@ public function enableModuleContentVersion(): bool {
 
 	/**
 	 * Get a setting from the repo or client settings, with repo overriding client.
+	 * @return mixed
 	 */
 	public function getSetting( string $settingName ) {
 		if ( $this->repoSettings->hasSetting( $settingName ) ) {

lib/includes/Serialization/SerializationModifier.php

@@ -38,7 +38,7 @@ public function modifyUsingCallbacks( array $array, array $modifications ): arra
 	 * Iterates the value and modifications and runs all the needed sub-modifications,
 	 * then runs the modifications of the current array level ('' key), if any.
 	 *
-	 * @param mixed $value The value to modify (usually an array except on leaf nodes).
+	 * @param mixed &$value The value to modify (usually an array except on leaf nodes).
 	 * @param array $modifications Modifications as returned by {@link unflattenPaths}.
 	 */
 	private function modifyUsingUnflattenedCallbacks( &$value, array $modifications ): void {

lib/includes/Store/Sql/TypeDispatchingWikiPageEntityMetaDataAccessor.php

@@ -45,7 +45,7 @@ class TypeDispatchingWikiPageEntityMetaDataAccessor implements WikiPageEntityMet
 	 * An associative array mapping entity types to instansiator callbacks.
 	 *  Callback signature: function( $databaseName, $repositoryName ): WikiPageEntityMetaDataAccessor
 	 *  Parameter Types: string|false $databaseName, string $repositoryName
-	 * @param WikiPageEntityMetaDataAccessor $defaultAccessor,
+	 * @param WikiPageEntityMetaDataAccessor $defaultAccessor
 	 * @param string|false $databaseName
 	 * @param string $repositoryName
 	 */

lib/packages/wikibase/data-model/src/Entity/SerializableEntityId.php

@@ -10,6 +10,7 @@
  */
 abstract class SerializableEntityId implements EntityId {
 
+	/** @var string */
 	protected $serialization;
 
 	public const PATTERN = '/^[^:]+\z/';

lib/packages/wikibase/data-model/src/Snak/PropertyValueSnak.php

@@ -19,6 +19,7 @@
  */
 class PropertyValueSnak extends SnakObject {
 
+	/** @var DataValue */
 	protected $dataValue;
 
 	/**

lib/tests/phpunit/Formatters/ItemPropertyIdHtmlLinkFormatterTest.php

@@ -609,6 +609,7 @@ private function givenPropertyDoesNotExist( $propertyId ) {
 
 	/**
 	 * @param string $propertyId
+	 * @return object
 	 */
 	private function givenPropertyExists( $propertyId ) {
 		$title = $this->createMock( Title::class );

lib/tests/phpunit/MockEntityRevisionLookup.php

@@ -8,6 +8,7 @@
 use Wikibase\Lib\Store\EntityRevisionLookup;
 use Wikibase\Lib\Store\LatestRevisionIdResult;
 use Wikibase\Lib\Store\LookupConstants;
+use Wikibase\Lib\Store\RedirectRevision;
 use Wikibase\Lib\Store\RevisionedUnresolvedRedirectException;
 use Wikibase\Lib\Store\StorageException;
 
@@ -19,8 +20,10 @@ class MockEntityRevisionLookup implements EntityRevisionLookup {
 	private $entities;
 
 	/**
-	 * @param [ Serialised EntityId ][ int $revisionId ][ RedirectEntityRevision $revision ] $redirects
-	 * @param [ Serialised EntityId ][ int $revisionId ][ EntityRevision $revision ] $entities
+	 * @param array<string,RedirectRevision> $redirects
+	 *  [ Serialised EntityId ][ RedirectEntityRevision $revision ]
+	 * @param array<string,array<int,EntityRevision>> $entities
+	 *  [ Serialised EntityId ][ int $revisionId ][ EntityRevision $revision ]
 	 */
 	public function __construct( array $redirects, array $entities ) {
 		$this->redirects = $redirects;

lib/tests/phpunit/SimpleCacheTestCase.php

@@ -23,7 +23,7 @@
 abstract class SimpleCacheTestCase extends TestCase {
 
 	/**
-	 * @var array with functionName => reason.
+	 * @var array<string,string> with functionName => reason.
 	 */
 	protected $skippedTests = [];
 

lib/tests/phpunit/SimpleCacheWithBagOStuffTest.php

@@ -16,6 +16,7 @@
  */
 class SimpleCacheWithBagOStuffTest extends SimpleCacheTestCase {
 
+	/** @var string[] */
 	protected $skippedTests = [
 		'testClear' => 'Not possible to implement for BagOStuff',
 	];

repo/includes/Content/EntityContent.php

@@ -238,7 +238,8 @@ public function getTextForSummary( $maxLength = 250 ) {
 	 * Returns an array structure for the redirect represented by this EntityContent, if any.
 	 *
 	 * @note This may or may not be consistent with what EntityContentCodec does.
-	 *       It it intended to be used primarily for diffing.
+	 *       It is intended to be used primarily for diffing.
+	 * @return string[]
 	 */
 	private function getRedirectData(): array {
 		// NOTE: keep in sync with getPatchedRedirect
@@ -261,7 +262,7 @@ private function getRedirectData(): array {
 	 * @note Avoid relying on this method! It bypasses EntityContentCodec, and does
 	 *       not make any guarantees about the structure of the array returned.
 	 *
-	 * @return array|EntityDocument An undefined data structure representing the content. This is
+	 * @return string[]|EntityDocument An undefined data structure representing the content. This is
 	 *  not guaranteed to conform to any serialization structure used in the database or externally.
 	 */
 	public function getNativeData() {

repo/includes/Content/EntityHandler.php

@@ -166,11 +166,7 @@ public function showMissingEntity( Title $title, IContextSource $context ) {
 			] ) . "\n$text\n</div>" );
 	}
 
-	/**
-	 * @see ContentHandler::getDiffEngineClass
-	 *
-	 * @return string
-	 */
+	/** @inheritDoc */
 	protected function getDiffEngineClass() {
 		return EntityContentDiffView::class;
 	}

repo/includes/Content/PropertyContent.php

@@ -120,7 +120,7 @@ public function getEntityPageProperties() {
 	 *
 	 * Returns false if the entity does not have a DataType set.
 	 *
-	 * @see Content::isValid()
+	 * @inheritDoc
 	 */
 	public function isValid() {
 		// TODO: provide a way to get the data type from the holder directly!

repo/includes/Hooks/Helpers/UserPreferredContentLanguagesLookup.php

@@ -37,7 +37,7 @@ public function __construct(
 	}
 
 	/**
-	 * @param $uiLanguage - user interface language; will be returned as the first language in the list if valid
+	 * @param string $uiLanguage User interface language; will be returned as the first language in the list if valid
 	 * @param User $user
 	 *
 	 * @return array language codes

repo/includes/Hooks/MakeGlobalVariablesScriptHookHandler.php

@@ -102,7 +102,7 @@ public static function factory(
 	}
 
 	/**
-	 * @param array $vars
+	 * @param array &$vars
 	 * @param OutputPage $out
 	 */
 	public function onMakeGlobalVariablesScript( &$vars, $out ): void {

repo/includes/ParserOutput/TermboxView.php

@@ -68,9 +68,7 @@ public function getTitleHtml( EntityId $entityId = null ) {
 		return $this->textProvider->getEscaped( 'parentheses', [ $entityId->getSerialization() ] );
 	}
 
-	/**
-	 * @see \Wikibase\View\ViewPlaceHolderEmitter
-	 */
+	/** @inheritDoc */
 	public function getPlaceholders(
 		EntityDocument $entity,
 		$revision,

repo/includes/Parsers/MwEraParser.php

@@ -103,7 +103,7 @@ private function parseEraWithMessage( string $value, string $msgText ): ?string
 
 	/**
 	 * Transform the message to a pattern we can match era against.
-	 * @param $msgText string
+	 * @param string $msgText
 	 * @return string
 	 */
 	private function getRegexpFromMessageText( $msgText ) {

repo/includes/RepoHooks.php

@@ -1122,7 +1122,7 @@ public static function onRegistration() {
 	 * or the 'edit' rate limit if no 'create' limit is defined,
 	 * unless the 'wikibase-idgenerator' rate limit was itself customized.
 	 *
-	 * @param array $rateLimits should be $wgRateLimits or a similar array
+	 * @param array &$rateLimits should be $wgRateLimits or a similar array
 	 */
 	public static function inheritDefaultRateLimits( array &$rateLimits ) {
 		if ( isset( $rateLimits['wikibase-idgenerator']['&inherit-create-edit'] ) ) {
@@ -1160,7 +1160,7 @@ public static function onApiMainOnException( $apiMain, $e ) {
 		$apiMain->getUser()->pingLimiter( RateLimitingIdGenerator::RATELIMIT_NAME, $idGeneratorInErrorPingLimiterValue );
 	}
 
-	/** @param ContentLanguages[] $contentLanguages */
+	/** @param ContentLanguages[] &$contentLanguages */
 	public static function onWikibaseContentLanguages( array &$contentLanguages ): void {
 		if ( !WikibaseRepo::getSettings()->getSetting( 'tmpEnableMulLanguageCode' ) ) {
 			return;

repo/includes/Store/ItemTermsRebuilder.php

@@ -35,7 +35,7 @@ class ItemTermsRebuilder {
 
 	/**
 	 * @param ItemTermStoreWriter $itemTermStoreWriter
-	 * @param $itemIdIterable
+	 * @param iterable $itemIdIterable
 	 * @param MessageReporter $progressReporter
 	 * @param MessageReporter $errorReporter
 	 * @param RepoDomainDb $db

repo/tests/phpunit/includes/Dumpers/JsonDumpGeneratorTest.php

@@ -145,7 +145,7 @@ protected function newDumpGenerator( array $ids = [], array $missingIds = [], ar
 	 * @param EntityId[] $ids
 	 * @param string $entityType
 	 * @param int $limit
-	 * @param int $offset
+	 * @param int &$offset
 	 *
 	 * @return EntityId[]
 	 */

repo/tests/phpunit/includes/EntityModificationTestHelper.php

@@ -172,7 +172,7 @@ public function serializeEntity( EntityDocument $entity ) {
 	 * Strip any fields we will likely not have in the arrays that are provided as
 	 * expected values. This includes empty fields, and automatic id or hash fields.
 	 *
-	 * @param array $data
+	 * @param array &$data
 	 */
 	private function unsetSpuriousFieldsRecursively( array &$data ) {
 		// unset empty fields