Add missing @param and @Result PHPDoc attributes

doctrine · Jun 20, 2021 · d875b1f · d875b1f
1 parent 7827869
commit d875b1f
Show file tree

Hide file tree

Showing 36 changed files with 139 additions and 120 deletions.
diff --git a/lib/Doctrine/ORM/Cache/Region.php b/lib/Doctrine/ORM/Cache/Region.php
@@ -57,7 +57,7 @@ public function get(CacheKey $key);
      *
      * @param CacheKey   $key   The key under which to cache the item.
      * @param CacheEntry $entry The entry to cache.
-     * @param Lock       $lock  The lock previously obtained.
+     * @param Lock|null  $lock  The lock previously obtained.
      *
      * @throws CacheException Indicates a problem accessing the region.
      */

diff --git a/lib/Doctrine/ORM/Configuration.php b/lib/Doctrine/ORM/Configuration.php
@@ -155,7 +155,8 @@ public function setMetadataDriverImpl(MappingDriver $driverImpl)
      * Adds a new default annotation driver with a correctly configured annotation reader. If $useSimpleAnnotationReader
      * is true, the notation `@Entity` will work, otherwise, the notation `@ORM\Entity` will be supported.
      *
-     * @param bool $useSimpleAnnotationReader
+     * @param string|string[] $paths
+     * @param bool            $useSimpleAnnotationReader
      * @psalm-param string|list<string> $paths
      *
      * @return AnnotationDriver
@@ -391,11 +392,9 @@ public function addNamedNativeQuery($name, $sql, Query\ResultSetMapping $rsm)
      *
      * @param string $name The name of the query.
      *
-     * @psalm-return array{string, ResultSetMapping} A tuple with the first
-     *                                               element being the SQL
-     *                                               string and the second
-     *                                               element being the
-     *                                               ResultSetMapping.
+     * @return mixed[]
+     * @psalm-return array{string, ResultSetMapping} A tuple with the first element being the SQL string and the second
+     *                                               element being the ResultSetMapping.
      *
      * @throws ORMException
      */
@@ -634,7 +633,8 @@ public function getCustomHydrationMode($modeName)
      * Adds a custom hydration mode.
      *
      * @param string $modeName The hydration mode name.
-     * @psalm-param class-string $hydrator The hydrator class name.
+     * @param string $hydrator The hydrator class name.
+     * @psalm-param class-string $hydrator
      *
      * @return void
      */

diff --git a/lib/Doctrine/ORM/EntityManager.php b/lib/Doctrine/ORM/EntityManager.php
@@ -885,9 +885,10 @@ public function initializeObject($obj)
     /**
      * Factory method to create EntityManager instances.
      *
-     * @param array<string, mixed>|Connection $connection   An array with the connection parameters or an existing Connection instance.
-     * @param Configuration                   $config       The Configuration instance to use.
-     * @param EventManager                    $eventManager The EventManager instance to use.
+     * @param mixed[]|Connection $connection   An array with the connection parameters or an existing Connection instance.
+     * @param Configuration      $config       The Configuration instance to use.
+     * @param EventManager|null  $eventManager The EventManager instance to use.
+     * @psalm-param array<string, mixed>|Connection $connection
      *
      * @return EntityManager The created EntityManager.
      *
@@ -908,9 +909,10 @@ public static function create($connection, Configuration $config, ?EventManager
     /**
      * Factory method to create Connection instances.
      *
-     * @param array<string, mixed>|Connection $connection   An array with the connection parameters or an existing Connection instance.
-     * @param Configuration                   $config       The Configuration instance to use.
-     * @param EventManager                    $eventManager The EventManager instance to use.
+     * @param mixed[]|Connection $connection   An array with the connection parameters or an existing Connection instance.
+     * @param Configuration      $config       The Configuration instance to use.
+     * @param EventManager|null  $eventManager The EventManager instance to use.
+     * @psalm-param array<string, mixed>|Connection $connection
      *
      * @return Connection
      *

diff --git a/lib/Doctrine/ORM/EntityRepository.php b/lib/Doctrine/ORM/EntityRepository.php
@@ -208,7 +208,8 @@ public function findAll()
      * @psalm-param array<string, mixed> $criteria
      * @psalm-param array<string, string>|null $orderBy
      *
-     * @psalm-return list<T> The objects.
+     * @return object[] The objects.
+     * @psalm-return list<T>
      */
     public function findBy(array $criteria, ?array $orderBy = null, $limit = null, $offset = null)
     {
@@ -250,7 +251,8 @@ public function count(array $criteria)
     /**
      * Adds support for magic method calls.
      *
-     * @param string $method
+     * @param string  $method
+     * @param mixed[] $arguments
      * @psalm-param list<mixed> $arguments
      *
      * @return mixed The returned value from the resolved method.

diff --git a/lib/Doctrine/ORM/Internal/Hydration/AbstractHydrator.php b/lib/Doctrine/ORM/Internal/Hydration/AbstractHydrator.php
@@ -412,9 +412,11 @@ protected function gatherRowData(array $data, array &$id, array &$nonemptyCompon
      * values according to their types. The resulting row has the same number
      * of elements as before.
      *
+     * @param mixed[] $data
      * @psalm-param array<string, mixed> $data
      *
-     * @psalm-return array<string, mixed> The processed row.
+     * @return mixed[] The processed row.
+     * @psalm-return array<string, mixed>
      */
     protected function gatherScalarRowData(&$data)
     {
@@ -448,6 +450,7 @@ protected function gatherScalarRowData(&$data)
      *
      * @param string $key Column name
      *
+     * @return mixed[]|null
      * @psalm-return array<string, mixed>|null
      */
     protected function hydrateColumnInfo($key)

diff --git a/lib/Doctrine/ORM/Internal/Hydration/HydrationException.php b/lib/Doctrine/ORM/Internal/Hydration/HydrationException.php
@@ -99,7 +99,8 @@ public static function missingDiscriminatorMetaMappingColumn($entityName, $discr
     }
 
     /**
-     * @param string $discrValue
+     * @param string   $discrValue
+     * @param string[] $discrMap
      * @psalm-param array<string, string> $discrMap
      *
      * @return HydrationException

diff --git a/lib/Doctrine/ORM/Mapping/ClassMetadataInfo.php b/lib/Doctrine/ORM/Mapping/ClassMetadataInfo.php
@@ -1314,7 +1314,8 @@ public function getFieldMapping($fieldName)
      * @param string $fieldName The field name that represents the association in
      *                          the object model.
      *
-     * @psalm-return array<string, mixed> The mapping.
+     * @return mixed[] The mapping.
+     * @psalm-return array<string, mixed>
      *
      * @throws MappingException
      */
@@ -1388,6 +1389,7 @@ public function getNamedQueries()
      *
      * @param string $queryName The query name.
      *
+     * @return mixed[]
      * @psalm-return array<string, mixed>
      *
      * @throws MappingException
@@ -2951,6 +2953,7 @@ public function hasLifecycleCallbacks($lifecycleEvent)
      *
      * @param string $event
      *
+     * @return string[]
      * @psalm-return list<string>
      */
     public function getLifecycleCallbacks($event)
@@ -3038,6 +3041,7 @@ public function addEntityListener($eventName, $class, $method)
      *
      * @see getDiscriminatorColumn()
      *
+     * @param mixed[] $columnDef
      * @psalm-param array<string, mixed> $columnDef
      *
      * @return void
@@ -3090,6 +3094,7 @@ public function setDiscriminatorMap(array $map)
      * Adds one entry of the discriminator map with a new class and corresponding name.
      *
      * @param string $name
+     * @param string $className
      * @psalm-param class-string $className
      *
      * @return void
@@ -3430,6 +3435,7 @@ public function getName()
      *
      * @param AbstractPlatform $platform
      *
+     * @return string[]
      * @psalm-return list<string>
      */
     public function getQuotedIdentifierColumnNames($platform)
@@ -3532,6 +3538,7 @@ public function getAssociationMappedByTargetField($fieldName)
     /**
      * @param string $targetClass
      *
+     * @return mixed[][]
      * @psalm-return array<string, array<string, mixed>>
      */
     public function getAssociationsByTargetClass($targetClass)

diff --git a/lib/Doctrine/ORM/Mapping/Driver/DatabaseDriver.php b/lib/Doctrine/ORM/Mapping/Driver/DatabaseDriver.php
@@ -145,6 +145,8 @@ public function setFieldNameForColumn($tableName, $columnName, $fieldName)
     /**
      * Sets tables manually instead of relying on the reverse engineering capabilities of SchemaManager.
      *
+     * @param Table[] $entityTables
+     * @param Table[] $manyToManyTables
      * @psalm-param list<Table> $entityTables
      * @psalm-param list<Table> $manyToManyTables
      *
@@ -380,21 +382,22 @@ private function buildFieldMappings(ClassMetadataInfo $metadata): void
     /**
      * Build field mapping from a schema column definition
      *
+     * @return mixed[]
      * @psalm-return array{
-     *                   fieldName: string,
-     *                   columnName: string,
-     *                   type: string,
-     *                   nullable: bool,
-     *                   options?: array{
-     *                       unsigned?: bool,
-     *                       fixed?: bool,
-     *                       comment?: string,
-     *                       default?: string
-     *                   },
-     *                   precision?: int,
-     *                   scale?: int,
-     *                   length?: int|null
-     *               }
+     *     fieldName: string,
+     *     columnName: string,
+     *     type: string,
+     *     nullable: bool,
+     *     options?: array{
+     *         unsigned?: bool,
+     *         fixed?: bool,
+     *         comment?: string,
+     *         default?: string
+     *     },
+     *     precision?: int,
+     *     scale?: int,
+     *     length?: int|null
+     * }
      */
     private function buildFieldMapping(string $tableName, Column $column): array
     {

diff --git a/lib/Doctrine/ORM/Mapping/MappingException.php b/lib/Doctrine/ORM/Mapping/MappingException.php
@@ -922,6 +922,9 @@ public static function infiniteEmbeddableNesting($className, $propertyName)
     }
 
     /**
+     * @param string $className
+     * @param string $propertyName
+     *
      * @return self
      */
     public static function illegalOverrideOfInheritedProperty($className, $propertyName)

diff --git a/lib/Doctrine/ORM/PersistentCollection.php b/lib/Doctrine/ORM/PersistentCollection.php
@@ -595,6 +595,7 @@ public function __sleep(): array
      * @param int      $offset
      * @param int|null $length
      *
+     * @return mixed[]
      * @psalm-return array<TKey,T>
      */
     public function slice($offset, $length = null): array
@@ -637,7 +638,7 @@ public function __clone()
      * Selects all elements from a selectable that match the expression and
      * return a new collection containing these elements.
      *
-     * @return Collection<TKey, T>
+     * @psalm-return Collection<TKey, T>
      *
      * @throws RuntimeException
      */

diff --git a/lib/Doctrine/ORM/Persisters/Collection/ManyToManyPersister.php b/lib/Doctrine/ORM/Persisters/Collection/ManyToManyPersister.php
@@ -298,7 +298,8 @@ public function loadCriteria(PersistentCollection $collection, Criteria $criteri
      * have to join in the actual entities table leading to additional
      * JOIN.
      *
-     * @psalm-param array<string, mixed> $mapping Array containing mapping information.
+     * @param mixed[] $mapping Array containing mapping information.
+     * @psalm-param array<string, mixed> $mapping
      *
      * @return string[] ordered tuple:
      *                   - JOIN condition to add to the SQL
@@ -350,6 +351,7 @@ protected function generateFilterConditionSQL(ClassMetadata $targetEntity, $targ
     /**
      * Generate ON condition
      *
+     * @param mixed[] $mapping
      * @psalm-param array<string, mixed> $mapping
      *
      * @return string[]
@@ -464,6 +466,7 @@ protected function getDeleteRowSQL(PersistentCollection $collection)
      *
      * @param mixed $element
      *
+     * @return mixed[]
      * @psalm-return list<mixed>
      */
     protected function getDeleteRowSQLParameters(PersistentCollection $collection, $element)
@@ -513,6 +516,7 @@ protected function getInsertRowSQL(PersistentCollection $collection)
      *
      * @param mixed $element
      *
+     * @return mixed[]
      * @psalm-return list<mixed>
      */
     protected function getInsertRowSQLParameters(PersistentCollection $collection, $element)

diff --git a/lib/Doctrine/ORM/Persisters/Entity/BasicEntityPersister.php b/lib/Doctrine/ORM/Persisters/Entity/BasicEntityPersister.php
@@ -1722,6 +1722,7 @@ private function getSelectConditionStatementColumnSQL(
      * Subclasses are supposed to override this method if they intend to change
      * or alter the criteria by which entities are selected.
      *
+     * @param mixed[]|null $assoc
      * @psalm-param array<string, mixed> $criteria
      * @psalm-param array<string, mixed>|null $assoc
      *
@@ -2009,7 +2010,8 @@ public function exists($entity, ?Criteria $extraConditions = null)
     /**
      * Generates the appropriate join SQL for the given join column.
      *
-     * @psalm-param array<array<string, mixed>> $joinColumns The join columns definition of an association.
+     * @param array[] $joinColumns The join columns definition of an association.
+     * @psalm-param array<array<string, mixed>> $joinColumns
      *
      * @return string LEFT JOIN if one of the columns is nullable, INNER JOIN otherwise.
      */

diff --git a/lib/Doctrine/ORM/Persisters/Entity/EntityPersister.php b/lib/Doctrine/ORM/Persisters/Entity/EntityPersister.php
@@ -103,9 +103,10 @@ public function expandCriteriaParameters(Criteria $criteria);
     /**
      * Gets the SQL WHERE condition for matching a field with a given value.
      *
-     * @param string      $field
-     * @param mixed       $value
-     * @param string|null $comparison
+     * @param string       $field
+     * @param mixed        $value
+     * @param mixed[]|null $assoc
+     * @param string|null  $comparison
      * @psalm-param array<string, mixed>|null  $assoc
      *
      * @return string
@@ -186,19 +187,21 @@ public function getOwningTable($fieldName);
     /**
      * Loads an entity by a list of field criteria.
      *
-     * @param object|null $entity   The entity to load the data into. If not specified, a new entity is created.
-     * @param int|null    $lockMode One of the \Doctrine\DBAL\LockMode::* constants
-     *                              or NULL if no specific lock mode should be used
-     *                              for loading the entity.
-     * @param int|null    $limit    Limit number of results.
-     * @psalm-param array<string, mixed>       $hints    Hints for entity creation.
-     * @psalm-param array<string, mixed>       $criteria The criteria by which
-     *                                                   to load the entity.
-     * @psalm-param array<string, mixed>|null  $assoc    The association that
-     *                                                   connects the entity to
-     *                                                   load to another entity,
-     *                                                   if any.
-     * @psalm-param array<string, string>|null $orderBy  Criteria to order by.
+     * @param mixed[]       $criteria The criteria by which to load the entity.
+     * @param object|null   $entity   The entity to load the data into. If not specified,
+     *                                a new entity is created.
+     * @param mixed[]|null  $assoc    The association that connects the entity
+     *                                to load to another entity, if any.
+     * @param mixed[]       $hints    Hints for entity creation.
+     * @param int|null      $lockMode One of the \Doctrine\DBAL\LockMode::* constants
+     *                                or NULL if no specific lock mode should be used
+     *                                for loading the entity.
+     * @param int|null      $limit    Limit number of results.
+     * @param string[]|null $orderBy  Criteria to order by.
+     * @psalm-param array<string, mixed>       $criteria
+     * @psalm-param array<string, mixed>|null  $assoc
+     * @psalm-param array<string, mixed>       $hints
+     * @psalm-param array<string, string>|null $orderBy
      *
      * @return object|null The loaded and managed entity instance or NULL if the entity can not be found.
      *

diff --git a/lib/Doctrine/ORM/Query/Expr/Base.php b/lib/Doctrine/ORM/Query/Expr/Base.php
@@ -60,6 +60,7 @@ public function __construct($args = [])
     }
 
     /**
+     * @param string[]|object[] $args
      * @psalm-param list<string|object> $args
      *
      * @return static

diff --git a/lib/Doctrine/ORM/Query/Expr/Func.php b/lib/Doctrine/ORM/Query/Expr/Func.php
@@ -38,7 +38,8 @@ class Func
     /**
      * Creates a function, with the given argument.
      *
-     * @param string $name
+     * @param string  $name
+     * @param mixed[] $arguments
      * @psalm-param list<mixed> $arguments
      */
     public function __construct($name, $arguments)