Add phpdoc for Collection generics

doctrine · Jun 24, 2024 · 688a9d1 · 688a9d1
1 parent 77b525e
commit 688a9d1
Show file tree

Hide file tree

Showing 8 changed files with 40 additions and 9 deletions.
diff --git a/docs/en/reference/aggregation-stage-reference.rst b/docs/en/reference/aggregation-stage-reference.rst
@@ -381,6 +381,7 @@ pipeline stages. Take the following relationship for example:
 
     class Orders
     {
+        /** @var Collection<Item> */
         #[ReferenceMany(
             targetDocument: Item::class,
             cascade: 'all',
@@ -412,6 +413,7 @@ to be considered when looking up one-to-one relationships:
 
     class Orders
     {
+        /** @var Collection<Item> */
         #[ReferenceOne(
             targetDocument: Item::class,
             cascade: 'all',

diff --git a/docs/en/reference/attributes-reference.rst b/docs/en/reference/attributes-reference.rst
@@ -217,6 +217,7 @@ Optional attributes:
 
     class User
     {
+        /** @var Collection<BookTag|SongTag> */
         #[EmbedMany(
             strategy:'set',
             discriminatorField:'type',
@@ -989,13 +990,13 @@ Optional attributes:
         /** @var Collection<Item> */
         #[ReferenceMany(
             strategy: 'set',
-            targetDocument: Documents\Item::class,
+            targetDocument: Item::class,
             cascade: 'all',
             sort: ['sort_field' => 'asc'],
             discriminatorField: 'type',
             discriminatorMap: [
-                'book' => Documents\BookItem::class,
-                'song' => Documents\SongItem::class,
+                'book' => BookItem::class,
+                'song' => SongItem::class,
             ],
             defaultDiscriminatorValue: 'book',
         )]

diff --git a/docs/en/reference/best-practices.rst b/docs/en/reference/best-practices.rst
@@ -69,3 +69,10 @@ Example:
             $this->articles = new ArrayCollection();
         }
     }
+
+.. note::
+
+   The properties' type hints must be ``Collection``, and cannot be
+   ``ArrayCollection``. When the ``User`` object is retrieved from the database,
+   the properties ``$addresses`` and ``$articles`` are instances of
+   ``Doctrine\ODM\MongoDB\PersistentCollection`` to track changes.
diff --git a/docs/en/reference/embedded-mapping.rst b/docs/en/reference/embedded-mapping.rst
@@ -73,7 +73,7 @@ Embed many documents:
         {
             // ...
 
-            /** @var Collection<PhoneNumber>
+            /** @var Collection<PhoneNumber> */
             #[EmbedMany(targetDocument: Phonenumber::class)]
             private Collection $phoneNumbers;
 
@@ -282,6 +282,8 @@ You can achieve this behavior by using the `storeEmptyArray` option for embedded
         class User
         {
             // ...
+
+            /** @var Collection<PhoneNumber> */
             #[EmbedMany(targetDocument: PhoneNumber::class, storeEmptyArray: true)]
             private Collection $phoneNumbers;
             // ...
@@ -299,5 +301,6 @@ You can achieve this behavior by using the `storeEmptyArray` option for embedded
                 <field name="number" type="string" />
           </embedded-document>
         </doctrine-mongo-mapping>
+
 Now, when the `$phoneNumbers` collection is empty, an empty array will be stored in the database for the `User`
 document's embedded `phoneNumbers` collection, even if there are no actual embedded documents in the collection.
diff --git a/docs/en/reference/indexes.rst b/docs/en/reference/indexes.rst
@@ -244,6 +244,7 @@ Now if we had a ``BlogPost`` document with the ``Comment`` document embedded man
         #[Index]
         private string $slug;
 
+        /** @var Collection<Comment> */
         #[EmbedMany(targetDocument: Comment::class)]
         private Collection $comments;
     }

diff --git a/docs/en/reference/priming-references.rst b/docs/en/reference/priming-references.rst
@@ -18,6 +18,7 @@ Consider the following abbreviated model:
     #[Document]
     class User
     {
+        /** @var Collection<Account> */
         #[ReferenceMany(targetDocument: Account::class)]
         private Collection $accounts;
     }
@@ -111,6 +112,7 @@ specifying them in the mapping:
     #[Document]
     class User
     {
+        /** @var Collection<Account> */
         #[ReferenceMany(targetDocument: Account::class, prime: ['user'])]
         private Collection $accounts;
     }

diff --git a/docs/en/reference/reference-mapping.rst b/docs/en/reference/reference-mapping.rst
@@ -200,6 +200,7 @@ in each `DBRef`_ object:
         {
             // ..
 
+            /** @var Collection<Album|Song> */
             #[ReferenceMany(
                 discriminatorMap: [
                     'album' => Album::class,
@@ -277,8 +278,11 @@ Example:
 
         <?php
 
-        #[ReferenceOne(targetDocument: Profile::class, storeAs: 'id')]
-        private Profile $profile;
+        class User
+        {
+            #[ReferenceOne(targetDocument: Profile::class, storeAs: 'id')]
+            private Profile $profile;
+        }
 
     .. code-block:: xml
 
@@ -323,8 +327,11 @@ referenced documents. You must explicitly enable this functionality:
 
         <?php
 
-        #[ReferenceOne(targetDocument: Profile::class, cascade: ['persist'])]
-        private Profile $profile;
+        class User
+        {
+            #[ReferenceOne(targetDocument: Profile::class, cascade: ['persist'])]
+            private Profile $profile;
+        }
 
     .. code-block:: xml
 
@@ -435,13 +442,16 @@ You can achieve this behavior by using the `storeEmptyArray` option.
 
     .. code-block:: php
         <?php
+
         #[Document]
         class User
         {
             // ...
+
             /** @var Collection<Account> */
             #[ReferenceMany(targetDocument: Account::class, storeEmptyArray: true)]
-            private Collection $accounts = [];
+            private Collection $accounts;
+
             // ...
         }
     .. code-block:: xml

diff --git a/docs/en/reference/trees.rst b/docs/en/reference/trees.rst
@@ -23,6 +23,7 @@ Full Tree in Single Document
         #[Field(type: 'string')]
         private string $body;
 
+        /** @var Collection<Comment> */
         #[EmbedMany(targetDocument: Comment::class)]
         private Collection $comments;
 
@@ -38,6 +39,7 @@ Full Tree in Single Document
         #[Field(type: 'string')]
         private string $text;
 
+        /** @var Collection<Comment> */
         #[EmbedMany(targetDocument: Comment::class)]
         private Collection $replies;
 
@@ -113,6 +115,7 @@ Child Reference
         #[Field(type: 'string')]
         private string $name;
 
+        /** @var Collection<Category> */
         #[ReferenceMany(targetDocument: Category::class)]
         #[Index]
         private Collection $children;
@@ -169,10 +172,12 @@ Array of Ancestors
         #[Id]
         private string $id;
 
+        /** @var Collection<Category> */
         #[ReferenceMany(targetDocument: Category::class)]
         #[Index]
         private Collection $ancestors;
 
+        /** @var Collection<Category> */
         #[ReferenceOne(targetDocument: Category::class)]
         #[Index]
         private ?Category $parent = null;