Add function documentation to private functions

Bug: T330644 Depends-On: I2914498869ee8dbee20ca8196ac70b7b70e83b44 Depends-On: I69fb434d5840af45977d0fbc8026faab274e3866 Depends-On: I9db4e5fa87a6d84300c5f9f4e3eddf497ec31739 Change-Id: I1c42b94b1b6683b78b2b4d326bdbecc3353935d3
wikimedia · Feb 13, 2025 · fa18665 · fa18665
1 parent ea14c33
commit fa18665
Show file tree

Hide file tree

Showing 36 changed files with 170 additions and 1 deletion.
diff --git a/.phpcs.xml b/.phpcs.xml
@@ -1,7 +1,6 @@
 <?xml version="1.0"?>
 <ruleset>
 	<rule ref="./vendor/mediawiki/mediawiki-codesniffer/MediaWiki">
-		<exclude name="MediaWiki.Commenting.FunctionComment.MissingDocumentationPrivate" />
 		<exclude name="MediaWiki.Commenting.FunctionComment.MissingDocumentationProtected" />
 		<exclude name="MediaWiki.Commenting.FunctionComment.MissingDocumentationPublic" />
 		<exclude name="MediaWiki.Commenting.FunctionComment.MissingParamTag" />

diff --git a/data-access/src/EntitySourceDefinitionsConfigParser.php b/data-access/src/EntitySourceDefinitionsConfigParser.php
@@ -126,6 +126,10 @@ private function validateDatabaseSourceConfigFields( $sourceData, $sourceName )
 		}
 	}
 
+	/**
+	 * @param int|string $namespaceAndSlot
+	 * @return array{0:int,1:string}
+	 */
 	private static function splitNamespaceAndSlot( $namespaceAndSlot ) {
 		if ( is_int( $namespaceAndSlot ) ) {
 			return [ $namespaceAndSlot, SlotRecord::MAIN ];

diff --git a/data-access/src/SourceAndTypeDispatchingPrefetchingTermLookup.php b/data-access/src/SourceAndTypeDispatchingPrefetchingTermLookup.php
@@ -61,6 +61,9 @@ public function getPrefetchedTerm( EntityId $entityId, $termType, $languageCode
 		)->getPrefetchedTerm( $entityId, $termType, $languageCode );
 	}
 
+	/**
+	 * @return PrefetchingTermLookup
+	 */
 	private function getLookupForEntitySourceAndType( EntitySource $source, string $type ) {
 		return $this->dispatcher->getServiceForSourceAndType( $source->getSourceName(), $type, [ $source ] );
 	}

diff --git a/lib/includes/ServiceBySourceAndTypeDispatcher.php b/lib/includes/ServiceBySourceAndTypeDispatcher.php
@@ -40,6 +40,9 @@ public function __construct( string $type, array $callbacks ) {
 		$this->serviceType = $type;
 	}
 
+	/**
+	 * @return mixed
+	 */
 	private function createService( string $sourceName, string $entityType, array $args = [] ) {
 		if ( isset( $this->callbacks[$sourceName][$entityType] ) ) {
 			$this->services[$sourceName][$entityType] = $this->callbacks[$sourceName][$entityType]( ...$args );

diff --git a/lib/includes/ServiceByTypeDispatcher.php b/lib/includes/ServiceByTypeDispatcher.php
@@ -59,6 +59,9 @@ public function getServiceForType( string $entityType, array $callbackArgs = []
 		return $this->services[$entityType] ?? $this->createService( $entityType, $callbackArgs );
 	}
 
+	/**
+	 * @return mixed
+	 */
 	private function createService( string $entityType, array $args = [] ) {
 		$this->services[$entityType] = $this->callbacks[$entityType]( ...$args );
 

diff --git a/lib/includes/SimpleCacheWithBagOStuff.php b/lib/includes/SimpleCacheWithBagOStuff.php
@@ -231,6 +231,7 @@ private function assertKeysAreValid( array $keys ): void {
 	}
 
 	/**
+	 * @param string $key
 	 * @throws CacheInvalidArgumentException
 	 */
 	private function assertKeyIsValid( $key ): void {
@@ -314,6 +315,10 @@ private function normalizeTtl( $ttl ) {
 		throw new CacheInvalidArgumentException( "Invalid TTL: `null|int|\DateInterval` expected, `$type` given" );
 	}
 
+	/**
+	 * @param mixed $value
+	 * @return string|false
+	 */
 	private function serialize( $value ) {
 		$dataToStore = serialize( $value );
 

diff --git a/lib/includes/Store/CachingPrefetchingTermLookup.php b/lib/includes/Store/CachingPrefetchingTermLookup.php
@@ -240,6 +240,9 @@ private function getPrefetchedTermsFromLookup(
 		return $terms;
 	}
 
+	/**
+	 * @return string|string[]|false|null
+	 */
 	private function getTermFromLookup( EntityId $entity, string $termType, string $language ) {
 		if ( $termType === TermTypes::TYPE_LABEL || $termType === TermTypes::TYPE_DESCRIPTION ) {
 			return $this->lookup->getPrefetchedTerm( $entity, $termType, $language );
@@ -308,6 +311,9 @@ private function getCacheKey( EntityId $id, string $language, string $termType )
 		return $this->buildCacheKey( $resolutionResult[1], $resolutionResult[0], $language, $termType );
 	}
 
+	/**
+	 * @return string|false|null
+	 */
 	private function getBufferedOrCachedEntry( EntityId $entityId, string $termType, string $languageCode ) {
 		// Check if it's prefetched already.
 		$prefetchedTerm = $this->getPrefetchedTerm( $entityId, $termType, $languageCode );

diff --git a/lib/packages/wikibase/changes/src/ItemChange.php b/lib/packages/wikibase/changes/src/ItemChange.php
@@ -49,6 +49,9 @@ private function getDiffFromSiteLinkChangesPerWiki( array $change ): Diff {
 		}
 	}
 
+	/**
+	 * @param mixed $obj
+	 */
 	private function logWarning( $obj ) {
 		// This shouldn't happen, but we should be robust against corrupt, incomplete
 		// or obsolete instances in the database, etc.

diff --git a/...ckages/wikibase/data-model-serialization/src/Deserializers/AliasGroupListDeserializer.php b/...ckages/wikibase/data-model-serialization/src/Deserializers/AliasGroupListDeserializer.php
@@ -71,6 +71,10 @@ private function deserializeAliasGroup( array $serialization, $languageCode ) {
 		return new AliasGroup( (string)$languageCode, $aliases );
 	}
 
+	/**
+	 * @param array $serialization
+	 * @param string $requestedLanguage
+	 */
 	private function assertIsValidAliasSerialization( $serialization, $requestedLanguage ) {
 		if ( !is_array( $serialization ) ) {
 			throw new DeserializationException( 'Term serializations must be arrays' );
@@ -86,6 +90,10 @@ private function assertIsValidAliasSerialization( $serialization, $requestedLang
 		$this->assertRequestedAndActualLanguageMatch( $serialization, $requestedLanguage );
 	}
 
+	/**
+	 * @param array $array
+	 * @param string $attributeName
+	 */
 	private function requireAttribute( array $array, $attributeName ) {
 		if ( !array_key_exists( $attributeName, $array ) ) {
 			throw new MissingAttributeException(
@@ -94,6 +102,10 @@ private function requireAttribute( array $array, $attributeName ) {
 		}
 	}
 
+	/**
+	 * @param array $array
+	 * @param string $key
+	 */
 	private function assertNotAttribute( array $array, $key ) {
 		if ( array_key_exists( $key, $array ) ) {
 			throw new InvalidAttributeException(
@@ -104,6 +116,10 @@ private function assertNotAttribute( array $array, $key ) {
 		}
 	}
 
+	/**
+	 * @param array $serialization
+	 * @param string $requestedLanguage
+	 */
 	private function assertRequestedAndActualLanguageMatch(
 		array $serialization,
 		$requestedLanguage
@@ -117,10 +133,19 @@ private function assertRequestedAndActualLanguageMatch(
 		}
 	}
 
+	/**
+	 * @param array $array
+	 * @param string $attributeName
+	 */
 	private function assertAttributeIsArray( array $array, $attributeName ) {
 		$this->assertAttributeInternalType( $array, $attributeName, 'array' );
 	}
 
+	/**
+	 * @param array $array
+	 * @param string $attributeName
+	 * @param string $internalType
+	 */
 	private function assertAttributeInternalType( array $array, $attributeName, $internalType ) {
 		if ( gettype( $array[$attributeName] ) !== $internalType ) {
 			throw new InvalidAttributeException(

diff --git a/lib/packages/wikibase/data-model-serialization/src/Deserializers/ReferenceDeserializer.php b/lib/packages/wikibase/data-model-serialization/src/Deserializers/ReferenceDeserializer.php
@@ -37,6 +37,9 @@ public function isDeserializerFor( $serialization ) {
 		return $this->isValidSerialization( $serialization );
 	}
 
+	/**
+	 * @param mixed $serialization
+	 */
 	private function isValidSerialization( $serialization ): bool {
 		return is_array( $serialization ) && array_key_exists( 'snaks', $serialization );
 	}

diff --git a/lib/packages/wikibase/data-model-serialization/src/Deserializers/SiteLinkDeserializer.php b/lib/packages/wikibase/data-model-serialization/src/Deserializers/SiteLinkDeserializer.php
@@ -66,6 +66,9 @@ private function getDeserializeBadges( array $serialization ): array {
 		return $badges;
 	}
 
+	/**
+	 * @param string $serialization
+	 */
 	private function deserializeItemId( $serialization ): ItemId {
 		$itemId = $this->entityIdDeserializer->deserialize( $serialization );
 
@@ -80,6 +83,9 @@ private function deserializeItemId( $serialization ): ItemId {
 		return $itemId;
 	}
 
+	/**
+	 * @param array $serialization
+	 */
 	private function assertBadgesIsArray( $serialization ) {
 		if ( !is_array( $serialization['badges'] ) ) {
 			throw new InvalidAttributeException(
@@ -90,11 +96,18 @@ private function assertBadgesIsArray( $serialization ) {
 		}
 	}
 
+	/**
+	 * @param array $serialization
+	 */
 	private function assertCanDeserialize( $serialization ) {
 		$this->requireAttribute( $serialization, 'site' );
 		$this->requireAttribute( $serialization, 'title' );
 	}
 
+	/**
+	 * @param array $serialization
+	 * @param string $attribute
+	 */
 	private function requireAttribute( $serialization, $attribute ) {
 		if ( !is_array( $serialization ) || !array_key_exists( $attribute, $serialization ) ) {
 			throw new MissingAttributeException( $attribute );

diff --git a/lib/packages/wikibase/data-model-serialization/src/Deserializers/SnakDeserializer.php b/lib/packages/wikibase/data-model-serialization/src/Deserializers/SnakDeserializer.php
@@ -137,6 +137,9 @@ private function deserializeDataValue( PropertyId $propertyId, array $serializat
 		}
 	}
 
+	/**
+	 * @param array $serialization
+	 */
 	private function assertValidDataValue( $serialization ): void {
 		if ( !is_array( $serialization ) || !array_key_exists( DataValueDeserializer::TYPE_KEY, $serialization ) ) {
 			throw new MissingTypeException( 'Not an array or missing the key "' . DataValueDeserializer::TYPE_KEY . '"' );
@@ -184,6 +187,9 @@ private function deserializePropertyId( string $serialization ): PropertyId {
 		);
 	}
 
+	/**
+	 * @param array $serialization
+	 */
 	private function assertCanDeserialize( $serialization ): void {
 		if ( !is_array( $serialization ) ) {
 			throw new DeserializationException( 'The snak serialization should be an array' );

diff --git a/lib/packages/wikibase/data-model-serialization/src/Deserializers/TermDeserializer.php b/lib/packages/wikibase/data-model-serialization/src/Deserializers/TermDeserializer.php
@@ -55,6 +55,10 @@ private function assertCanDeserialize( $serialization ) {
 		$this->assertAttributeIsString( $serialization, 'value' );
 	}
 
+	/**
+	 * @param array $array
+	 * @param string $attributeName
+	 */
 	private function assertAttributeIsString( array $array, $attributeName ) {
 		if ( !is_string( $array[$attributeName] ) ) {
 			throw new InvalidAttributeException(

diff --git a/lib/packages/wikibase/data-model-serialization/src/Deserializers/TermListDeserializer.php b/lib/packages/wikibase/data-model-serialization/src/Deserializers/TermListDeserializer.php
@@ -62,6 +62,10 @@ private function getDeserialized( array $serialization ) {
 		return $termList;
 	}
 
+	/**
+	 * @param array $serialization
+	 * @param string $requestedLanguage
+	 */
 	private function assertRequestedAndActualLanguageMatch(
 		array $serialization,
 		$requestedLanguage
@@ -75,6 +79,10 @@ private function assertRequestedAndActualLanguageMatch(
 		}
 	}
 
+	/**
+	 * @param array $array
+	 * @param string $attributeName
+	 */
 	private function assertAttributeIsArray( array $array, $attributeName ) {
 		if ( !is_array( $array[$attributeName] ) ) {
 			throw new InvalidAttributeException(

diff --git a/lib/packages/wikibase/data-model-serialization/src/Serializers/AliasGroupListSerializer.php b/lib/packages/wikibase/data-model-serialization/src/Serializers/AliasGroupListSerializer.php
@@ -33,6 +33,9 @@ public function serialize( $object ) {
 		return $this->serializeMap( $this->generateSerializedArrayRepresentation( $object ) );
 	}
 
+	/**
+	 * @param AliasGroupList $object
+	 */
 	private function assertIsSerializerFor( $object ) {
 		if ( !( $object instanceof AliasGroupList ) ) {
 			throw new UnsupportedObjectException(

diff --git a/lib/packages/wikibase/data-model-serialization/src/Serializers/AliasGroupSerializer.php b/lib/packages/wikibase/data-model-serialization/src/Serializers/AliasGroupSerializer.php
@@ -27,6 +27,9 @@ public function serialize( $object ) {
 		return $this->getSerialized( $object );
 	}
 
+	/**
+	 * @param AliasGroup $object
+	 */
 	private function assertIsSerializerFor( $object ) {
 		if ( !( $object instanceof AliasGroup ) ) {
 			throw new UnsupportedObjectException(

diff --git a/lib/packages/wikibase/data-model-serialization/src/Serializers/TermListSerializer.php b/lib/packages/wikibase/data-model-serialization/src/Serializers/TermListSerializer.php
@@ -37,6 +37,9 @@ public function serialize( $object ) {
 		return $this->serializeMap( $this->generateSerializedArrayRepresentation( $object ) );
 	}
 
+	/**
+	 * @param TermList $object
+	 */
 	private function assertIsSerializerFor( $object ) {
 		if ( !( $object instanceof TermList ) ) {
 			throw new UnsupportedObjectException(

diff --git a/lib/packages/wikibase/data-model-serialization/src/Serializers/TermSerializer.php b/lib/packages/wikibase/data-model-serialization/src/Serializers/TermSerializer.php
@@ -25,6 +25,9 @@ public function serialize( $object ) {
 		return $this->getSerialized( $object );
 	}
 
+	/**
+	 * @param Term $object
+	 */
 	private function assertIsSerializerFor( $object ) {
 		if ( !( $object instanceof Term ) ) {
 			throw new UnsupportedObjectException(

diff --git a/lib/packages/wikibase/data-model-serialization/src/Serializers/TypedSnakSerializer.php b/lib/packages/wikibase/data-model-serialization/src/Serializers/TypedSnakSerializer.php
@@ -38,6 +38,9 @@ public function serialize( $object ) {
 		return $this->getSerialized( $object );
 	}
 
+	/**
+	 * @param TypedSnak $object
+	 */
 	private function assertIsSerializerFor( $object ) {
 		if ( !( $object instanceof TypedSnak ) ) {
 			throw new UnsupportedObjectException(

diff --git a/lib/packages/wikibase/data-model-services/src/ByPropertyIdGrouper.php b/lib/packages/wikibase/data-model-services/src/ByPropertyIdGrouper.php
@@ -33,6 +33,9 @@ public function __construct( $propertyIdProviders ) {
 		$this->indexPropertyIdProviders( $propertyIdProviders );
 	}
 
+	/**
+	 * @param PropertyIdProvider[]|Traversable $propertyIdProviders
+	 */
 	private function assertArePropertyIdProviders( $propertyIdProviders ) {
 		if ( !is_iterable( $propertyIdProviders ) ) {
 			throw new InvalidArgumentException( '$propertyIdProviders must be an array or an instance of Traversable' );

diff --git a/lib/packages/wikibase/data-model/src/Entity/ItemId.php b/lib/packages/wikibase/data-model/src/Entity/ItemId.php
@@ -26,6 +26,9 @@ public function __construct( $idSerialization ) {
 		parent::__construct( strtoupper( $idSerialization ) );
 	}
 
+	/**
+	 * @param string $idSerialization
+	 */
 	private function assertValidIdFormat( $idSerialization ) {
 		if ( !is_string( $idSerialization ) ) {
 			throw new InvalidArgumentException( '$idSerialization must be a string' );

diff --git a/lib/packages/wikibase/data-model/src/Entity/NumericPropertyId.php b/lib/packages/wikibase/data-model/src/Entity/NumericPropertyId.php
@@ -22,6 +22,9 @@ public function __construct( $idSerialization ) {
 		parent::__construct( strtoupper( $idSerialization ) );
 	}
 
+	/**
+	 * @param string $idSerialization
+	 */
 	private function assertValidIdFormat( $idSerialization ) {
 		if ( !is_string( $idSerialization ) ) {
 			throw new InvalidArgumentException( '$idSerialization must be a string' );

diff --git a/lib/packages/wikibase/data-model/src/Entity/SerializableEntityId.php b/lib/packages/wikibase/data-model/src/Entity/SerializableEntityId.php
@@ -25,6 +25,9 @@ public function __construct( $serialization ) {
 		$this->serialization = self::normalizeIdSerialization( $serialization );
 	}
 
+	/**
+	 * @param string $serialization
+	 */
 	private static function assertValidSerialization( $serialization ) {
 		if ( !is_string( $serialization ) ) {
 			throw new InvalidArgumentException( '$serialization must be a string' );

diff --git a/lib/packages/wikibase/data-model/src/Statement/StatementByGuidMap.php b/lib/packages/wikibase/data-model/src/Statement/StatementByGuidMap.php
@@ -64,6 +64,9 @@ public function hasStatementWithGuid( $statementGuid ) {
 		return array_key_exists( $statementGuid, $this->statements );
 	}
 
+	/**
+	 * @param string $statementGuid
+	 */
 	private function assertIsStatementGuid( $statementGuid ) {
 		if ( !is_string( $statementGuid ) ) {
 			throw new InvalidArgumentException( '$statementGuid needs to be a string' );

diff --git a/...packages/wikibase/internal-serialization/src/Deserializers/LegacyEntityIdDeserializer.php b/...packages/wikibase/internal-serialization/src/Deserializers/LegacyEntityIdDeserializer.php
@@ -41,6 +41,9 @@ public function deserialize( $serialization ) {
 		}
 	}
 
+	/**
+	 * @param array $serialization
+	 */
 	private function isLegacyFormat( $serialization ): bool {
 		return is_array( $serialization ) && count( $serialization ) == 2
 			&& array_key_exists( 0, $serialization ) && array_key_exists( 1, $serialization );

diff --git a/lib/packages/wikibase/internal-serialization/src/Deserializers/LegacyItemDeserializer.php b/lib/packages/wikibase/internal-serialization/src/Deserializers/LegacyItemDeserializer.php
@@ -126,6 +126,9 @@ private function getStatement( array $claimSerialization ) {
 		return $this->statementDeserializer->deserialize( $statementSerialization );
 	}
 
+	/**
+	 * @param array $value
+	 */
 	private function assertClaimValueIsArray( $value ) {
 		if ( !is_array( $value ) ) {
 			throw new DeserializationException( 'Claim serialization must be an array.' );