From 2ecfee9751548be56d7e3c17dd681e70efb37e37 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gr=C3=A9goire=20Paris?= <postmaster@greg0ire.fr>
Date: Wed, 12 Oct 2022 21:18:59 +0200
Subject: [PATCH] Modernize documentation code

- migrate to attributes;
- add helpful phpdoc annotations;
- use typed properties;
- add type declarations.
---
 docs/en/reference/association-mapping.rst     | 236 ++++++++----------
 docs/en/reference/faq.rst                     |   9 +-
 docs/en/reference/security.rst                |  25 +-
 .../reference/working-with-associations.rst   | 120 ++++-----
 docs/en/tutorials/composite-primary-keys.rst  |  25 +-
 5 files changed, 201 insertions(+), 214 deletions(-)

diff --git a/docs/en/reference/association-mapping.rst b/docs/en/reference/association-mapping.rst
index 8dbcd1f19a6..c97af40afbe 100644
--- a/docs/en/reference/association-mapping.rst
+++ b/docs/en/reference/association-mapping.rst
@@ -40,19 +40,17 @@ A many-to-one association is the most common association between objects. Exampl
     .. code-block:: php
 
         <?php
-        /** @Entity */
+        #[Entity]
         class User
         {
             // ...
 
-            /**
-             * @ManyToOne(targetEntity="Address")
-             * @JoinColumn(name="address_id", referencedColumnName="id")
-             */
-            private $address;
+            #[ManyToOne(targetEntity: Address::class)]
+            #[JoinColumn(name: 'address_id', referencedColumnName: 'id')]
+            private Address|null $address;
         }
 
-        /** @Entity */
+        #[Entity]
         class Address
         {
             // ...
@@ -82,7 +80,7 @@ A many-to-one association is the most common association between objects. Exampl
 
 .. note::
 
-    The above ``@JoinColumn`` is optional as it would default
+    The above ``#[JoinColumn]`` is optional as it would default
     to ``address_id`` and ``id`` anyways. You can omit it and let it
     use the defaults.
 
@@ -114,22 +112,20 @@ references one ``Shipment`` entity.
     .. code-block:: php
 
         <?php
-        /** @Entity */
+        #[Entity]
         class Product
         {
             // ...
 
-            /**
-             * One Product has One Shipment.
-             * @OneToOne(targetEntity="Shipment")
-             * @JoinColumn(name="shipment_id", referencedColumnName="id")
-             */
+            /** One Product has One Shipment. */
+            #[OneToOne(targetEntity: Shipment::class)]
+            #[JoinColumn(name: 'shipment_id', referencedColumnName: 'id')]
             private $shipment;
 
             // ...
         }
 
-        /** @Entity */
+        #[Entity]
         class Shipment
         {
             // ...
@@ -156,7 +152,7 @@ references one ``Shipment`` entity.
                 name: shipment_id
                 referencedColumnName: id
 
-Note that the @JoinColumn is not really necessary in this example,
+Note that the ``#[JoinColumn]`` is not really necessary in this example,
 as the defaults would be the same.
 
 Generated MySQL Schema:
@@ -191,31 +187,27 @@ object.
     .. code-block:: php
 
         <?php
-        /** @Entity */
+        #[Entity]
         class Customer
         {
             // ...
 
-            /**
-             * One Customer has One Cart.
-             * @OneToOne(targetEntity="Cart", mappedBy="customer")
-             */
-            private $cart;
+            /** One Customer has One Cart. */
+            #[OneToOne(targetEntity: Cart::class, mappedBy: 'customer')]
+            private Cart|null $cart;
 
             // ...
         }
 
-        /** @Entity */
+        #[Entity]
         class Cart
         {
             // ...
 
-            /**
-             * One Cart has One Customer.
-             * @OneToOne(targetEntity="Customer", inversedBy="cart")
-             * @JoinColumn(name="customer_id", referencedColumnName="id")
-             */
-            private $customer;
+            /** One Cart has One Customer. */
+            #[OneToOne(targetEntity: Customer::class, inversedBy: 'cart')]
+            #[JoinColumn(name: 'customer_id', referencedColumnName: 'id')]
+            private Customer|null $customer;
 
             // ...
         }
@@ -281,16 +273,14 @@ below.
 .. code-block:: php
 
     <?php
-    /** @Entity */
+    #[Entity]
     class Student
     {
         // ...
 
-        /**
-         * One Student has One Mentor.
-         * @OneToOne(targetEntity="Student")
-         * @JoinColumn(name="mentor_id", referencedColumnName="id")
-         */
+        /** One Student has One Mentor. */
+        #[OneToOne(targetEntity: Student::class)]
+        #[JoinColumn(name: 'mentor_id', referencedColumnName: 'id')]
         private $mentor;
 
         // ...
@@ -331,15 +321,16 @@ bidirectional many-to-one.
         <?php
         use Doctrine\Common\Collections\ArrayCollection;
 
-        /** @Entity */
+        #[Entity]
         class Product
         {
             // ...
             /**
              * One product has many features. This is the inverse side.
-             * @OneToMany(targetEntity="Feature", mappedBy="product")
+             * @var Collection<int, Feature>
              */
-            private $features;
+            #[OneToMany(targetEntity: Feature::class, mappedBy: 'product')]
+            private Collection $features;
             // ...
 
             public function __construct() {
@@ -347,16 +338,14 @@ bidirectional many-to-one.
             }
         }
 
-        /** @Entity */
+        #[Entity]
         class Feature
         {
             // ...
-            /**
-             * Many features have one product. This is the owning side.
-             * @ManyToOne(targetEntity="Product", inversedBy="features")
-             * @JoinColumn(name="product_id", referencedColumnName="id")
-             */
-            private $product;
+            /** Many features have one product. This is the owning side. */
+            #[ManyToOne(targetEntity: Product::class, inversedBy: 'features')]
+            #[JoinColumn(name: 'product_id', referencedColumnName: 'id')]
+            private Product|null $product;
             // ...
         }
 
@@ -424,30 +413,30 @@ The following example sets up such a unidirectional one-to-many association:
     .. code-block:: php
 
         <?php
-        /** @Entity */
+        #[Entity]
         class User
         {
             // ...
 
             /**
              * Many Users have Many Phonenumbers.
-             * @ManyToMany(targetEntity="Phonenumber")
-             * @JoinTable(name="users_phonenumbers",
-             *      joinColumns={@JoinColumn(name="user_id", referencedColumnName="id")},
-             *      inverseJoinColumns={@JoinColumn(name="phonenumber_id", referencedColumnName="id", unique=true)}
-             *      )
+             * @var Collection<int, Phonenumber>
              */
-            private $phonenumbers;
+            #[ORM\JoinTable(name: 'users_phonenumbers')]
+            #[ORM\JoinColumn(name: 'user_id', referencedColumnName: 'id')]
+            #[ORM\InverseJoinColumn(name: 'phonenumber_id', referencedColumnName: 'id', unique: true)]
+            #[ORM\ManyToMany(targetEntity: 'Phonenumber')]
+            private Collection $phonenumbers;
 
             public function __construct()
             {
-                $this->phonenumbers = new \Doctrine\Common\Collections\ArrayCollection();
+                $this->phonenumbers = new ArrayCollection();
             }
 
             // ...
         }
 
-        /** @Entity */
+        #[Entity]
         class Phonenumber
         {
             // ...
@@ -526,26 +515,25 @@ database perspective is known as an adjacency list approach.
     .. code-block:: php
 
         <?php
-        /** @Entity */
+        #[Entity]
         class Category
         {
             // ...
             /**
              * One Category has Many Categories.
-             * @OneToMany(targetEntity="Category", mappedBy="parent")
+             * @var Collection<int, Category>
              */
-            private $children;
+            #[OneToMany(targetEntity: Category::class, mappedBy: 'parent')]
+            private Collection $children;
 
-            /**
-             * Many Categories have One Category.
-             * @ManyToOne(targetEntity="Category", inversedBy="children")
-             * @JoinColumn(name="parent_id", referencedColumnName="id")
-             */
-            private $parent;
+            /** Many Categories have One Category. */
+            #[ManyToOne(targetEntity: Category::class, inversedBy: 'children')]
+            #[JoinColumn(name: 'parent_id', referencedColumnName: 'id')]
+            private Category|null $parent;
             // ...
 
             public function __construct() {
-                $this->children = new \Doctrine\Common\Collections\ArrayCollection();
+                $this->children = new ArrayCollection();
             }
         }
 
@@ -597,29 +585,29 @@ entities:
     .. code-block:: php
 
         <?php
-        /** @Entity */
+        #[Entity]
         class User
         {
             // ...
 
             /**
              * Many Users have Many Groups.
-             * @ManyToMany(targetEntity="Group")
-             * @JoinTable(name="users_groups",
-             *      joinColumns={@JoinColumn(name="user_id", referencedColumnName="id")},
-             *      inverseJoinColumns={@JoinColumn(name="group_id", referencedColumnName="id")}
-             *      )
+             * @var Collection<int, Group>
              */
-            private $groups;
+             #[ORM\JoinTable(name: 'users_groups')]
++            #[ORM\JoinColumn(name: 'user_id', referencedColumnName: 'id')]
++            #[ORM\InverseJoinColumn(name: 'group_id', referencedColumnName: 'id')]
++            #[ORM\ManyToMany(targetEntity: Group::class)]
+            private Collection $groups;
 
             // ...
 
             public function __construct() {
-                $this->groups = new \Doctrine\Common\Collections\ArrayCollection();
+                $this->groups = new ArrayCollection();
             }
         }
 
-        /** @Entity */
+        #[Entity]
         class Group
         {
             // ...
@@ -698,37 +686,39 @@ one is bidirectional.
     .. code-block:: php
 
         <?php
-        /** @Entity */
+        #[Entity]
         class User
         {
             // ...
 
             /**
              * Many Users have Many Groups.
-             * @ManyToMany(targetEntity="Group", inversedBy="users")
-             * @JoinTable(name="users_groups")
+             * @var Collection<int, Group>
              */
-            private $groups;
+            #[ManyToMany(targetEntity: Group::class, inversedBy: 'users')]
+            #[JoinTable(name: 'users_groups')]
+            private Collection $groups;
 
             public function __construct() {
-                $this->groups = new \Doctrine\Common\Collections\ArrayCollection();
+                $this->groups = new ArrayCollection();
             }
 
             // ...
         }
 
-        /** @Entity */
+        #[Entity]
         class Group
         {
             // ...
             /**
              * Many Groups have Many Users.
-             * @ManyToMany(targetEntity="User", mappedBy="groups")
+             * @var Collection<int, User>
              */
-            private $users;
+            #[ManyToMany(targetEntity: User::class, mappedBy: 'groups')]
+            private Collection $users;
 
             public function __construct() {
-                $this->users = new \Doctrine\Common\Collections\ArrayCollection();
+                $this->users = new ArrayCollection();
             }
 
             // ...
@@ -806,9 +796,9 @@ understandable:
     <?php
     class Article
     {
-        private $tags;
+        private Collection $tags;
 
-        public function addTag(Tag $tag)
+        public function addTag(Tag $tag): void
         {
             $tag->addArticle($this); // synchronously updating inverse side
             $this->tags[] = $tag;
@@ -817,9 +807,9 @@ understandable:
 
     class Tag
     {
-        private $articles;
+        private Collection $articles;
 
-        public function addArticle(Article $article)
+        public function addArticle(Article $article): void
         {
             $this->articles[] = $article;
         }
@@ -847,30 +837,31 @@ field named ``$friendsWithMe`` and ``$myFriends``.
 .. code-block:: php
 
     <?php
-    /** @Entity */
+    #[Entity]
     class User
     {
         // ...
 
         /**
          * Many Users have Many Users.
-         * @ManyToMany(targetEntity="User", mappedBy="myFriends")
+         * @var Collection<int, User>
          */
-        private $friendsWithMe;
+        #[ManyToMany(targetEntity: User::class, mappedBy: 'myFriends')]
+        private Collection $friendsWithMe;
 
         /**
          * Many Users have many Users.
-         * @ManyToMany(targetEntity="User", inversedBy="friendsWithMe")
-         * @JoinTable(name="friends",
-         *      joinColumns={@JoinColumn(name="user_id", referencedColumnName="id")},
-         *      inverseJoinColumns={@JoinColumn(name="friend_user_id", referencedColumnName="id")}
-         *      )
+         * @var Collection<int, User>
          */
-        private $myFriends;
+        #[ORM\JoinTable(name: 'friends')]
+        #[ORM\JoinColumn(name: 'user_id', referencedColumnName: 'id')]
+        #[ORM\InverseJoinColumn(name: 'friend_user_id', referencedColumnName: 'id')]
+        #[ORM\ManyToMany(targetEntity: 'User', inversedBy: 'friendsWithMe')]
+        private Collection $myFriends;
 
         public function __construct() {
-            $this->friendsWithMe = new \Doctrine\Common\Collections\ArrayCollection();
-            $this->myFriends = new \Doctrine\Common\Collections\ArrayCollection();
+            $this->friendsWithMe = new ArrayCollection();
+            $this->myFriends = new ArrayCollection();
         }
 
         // ...
@@ -913,8 +904,8 @@ As an example, consider this mapping:
     .. code-block:: php
 
         <?php
-        /** @OneToOne(targetEntity="Shipment") */
-        private $shipment;
+        #[OneToOne(targetEntity: Shipment::class)]
+        private Shipment|null $shipment;
 
     .. code-block:: xml
 
@@ -940,12 +931,10 @@ mapping:
     .. code-block:: php
 
         <?php
-        /**
-         * One Product has One Shipment.
-         * @OneToOne(targetEntity="Shipment")
-         * @JoinColumn(name="shipment_id", referencedColumnName="id")
-         */
-        private $shipment;
+        /** One Product has One Shipment. */
+        #[OneToOne(targetEntity: Shipment::class)]
+        #[JoinColumn(name: 'shipment_id', referencedColumnName: 'id')]
+        private Shipment|null $shipment;
 
     .. code-block:: xml
 
@@ -979,8 +968,8 @@ similar defaults. As an example, consider this mapping:
         class User
         {
             // ...
-            /** @ManyToMany(targetEntity="Group") */
-            private $groups;
+            #[ManyToMany(targetEntity: Group::class)]
+            private Collection $groups;
             // ...
         }
 
@@ -1012,13 +1001,13 @@ This is essentially the same as the following, more verbose, mapping:
             // ...
             /**
              * Many Users have Many Groups.
-             * @ManyToMany(targetEntity="Group")
-             * @JoinTable(name="User_Group",
-             *      joinColumns={@JoinColumn(name="User_id", referencedColumnName="id")},
-             *      inverseJoinColumns={@JoinColumn(name="Group_id", referencedColumnName="id")}
-             *      )
+             * @var Collection<int, Group>
              */
-            private $groups;
+            #[ORM\JoinTable(name: 'User_Group')]
+            #[ORM\JoinColumn(name: 'User_id', referencedColumnName: 'id')]
+            #[ORM\InverseJoinColumn(name: 'Group_id', referencedColumnName: 'id')]
+            #[ORM\ManyToMany(targetEntity: Group::class)]
+            private Collection $groups;
             // ...
         }
 
@@ -1072,7 +1061,7 @@ attribute on ``JoinColumn`` will be inherited from PHP type. So that:
     .. code-block:: php
 
         <?php
-        /** @OneToOne */
+        #[OneToOne]
         private Shipment $shipment;
 
     .. code-block:: xml
@@ -1097,11 +1086,9 @@ Is essentially the same as following:
     .. code-block:: php
 
         <?php
-        /**
-         * One Product has One Shipment.
-         * @OneToOne(targetEntity="Shipment")
-         * @JoinColumn(name="shipment_id", referencedColumnName="id", nullable=false)
-         */
+        /** One Product has One Shipment. */
+        #[OneToOne(targetEntity: Shipment::class)]
+        #[JoinColumn(name: 'shipment_id', referencedColumnName: 'id', nullable: false)]
         private Shipment $shipment;
 
     .. code-block:: xml
@@ -1163,15 +1150,12 @@ and ``@ManyToMany`` associations in the constructor of your entities:
     use Doctrine\Common\Collections\Collection;
     use Doctrine\Common\Collections\ArrayCollection;
 
-    /** @Entity */
+    #[Entity]
     class User
     {
-        /**
-         * Many Users have Many Groups.
-         * @var Collection
-         * @ManyToMany(targetEntity="Group")
-         */
-        private $groups;
+        /** Many Users have Many Groups. */
+        #[ManyToMany(targetEntity: Group::class)]
+        private Collection $groups;
 
         public function __construct()
         {
diff --git a/docs/en/reference/faq.rst b/docs/en/reference/faq.rst
index d5e86863a76..06edf9458b9 100644
--- a/docs/en/reference/faq.rst
+++ b/docs/en/reference/faq.rst
@@ -32,11 +32,12 @@ upon insert:
 
     class User
     {
-        const STATUS_DISABLED = 0;
-        const STATUS_ENABLED = 1;
+        private const STATUS_DISABLED = 0;
+        private const STATUS_ENABLED = 1;
 
-        private $algorithm = "sha1";
-        private $status = self:STATUS_DISABLED;
+        private string $algorithm = "sha1";
+        /** @var self::STATUS_* */
+        private int $status = self:STATUS_DISABLED;
     }
 
 .
diff --git a/docs/en/reference/security.rst b/docs/en/reference/security.rst
index 83d64dda871..d0b3e9e2420 100644
--- a/docs/en/reference/security.rst
+++ b/docs/en/reference/security.rst
@@ -98,19 +98,20 @@ entity might look like this:
 
     <?php
 
-    /**
-     * @Entity
-     */
+    #[Entity]
     class InsecureEntity
     {
-        /** @Id @Column(type="integer") @GeneratedValue */
-        private $id;
-        /** @Column */
-        private $email;
-        /** @Column(type="boolean") */
-        private $isAdmin;
-
-        public function fromArray(array $userInput)
+        #[Id, Column(type: 'integer'), GeneratedValue]
+        private int|null $id;
+
+        #[Column]
+        private string $email;
+
+        #[Column(type: 'boolean')]
+        private bool $isAdmin;
+
+        /** @param array<string, mixed> $userInput */
+        public function fromArray(array $userInput): void
         {
             foreach ($userInput as $key => $value) {
                 $this->$key = $value;
@@ -118,7 +119,7 @@ entity might look like this:
         }
     }
 
-Now the possiblity of mass-asignment exists on this entity and can
+Now the possiblity of mass-assignment exists on this entity and can
 be exploited by attackers to set the "isAdmin" flag to true on any
 object when you pass the whole request data to this method like:
 
diff --git a/docs/en/reference/working-with-associations.rst b/docs/en/reference/working-with-associations.rst
index 510d85f05b3..13376b4d86c 100644
--- a/docs/en/reference/working-with-associations.rst
+++ b/docs/en/reference/working-with-associations.rst
@@ -32,62 +32,64 @@ information about its type and if it's the owning or inverse side.
 .. code-block:: php
 
     <?php
-    /** @Entity */
+    #[Entity]
     class User
     {
-        /** @Id @GeneratedValue @Column(type="string") */
-        private $id;
+        #[Id, GeneratedValue, Column(type: 'integer')]
+        private int|null $id;
 
         /**
          * Bidirectional - Many users have Many favorite comments (OWNING SIDE)
          *
-         * @ManyToMany(targetEntity="Comment", inversedBy="userFavorites")
-         * @JoinTable(name="user_favorite_comments")
+         * @var Collection<int, Comment>
          */
-        private $favorites;
+        #[ManyToMany(targetEntity: Comment::class, inversedBy: 'userFavorites')]
+        #[JoinTable(name: 'user_favorite_comments')]
+        private Collection $favorites;
 
         /**
          * Unidirectional - Many users have marked many comments as read
          *
-         * @ManyToMany(targetEntity="Comment")
-         * @JoinTable(name="user_read_comments")
+         * @var Collection<int, Comment>
          */
-        private $commentsRead;
+        #[ManyToMany(targetEntity: Comment::class)]
+        #[JoinTable(name: 'user_read_comments')]
+        private Collection $commentsRead;
 
         /**
          * Bidirectional - One-To-Many (INVERSE SIDE)
          *
-         * @OneToMany(targetEntity="Comment", mappedBy="author")
+         * @var Collection<int, Comment>
          */
-        private $commentsAuthored;
+        #[OneToMany(targetEntity: Comment::class, mappedBy: 'author')]
+        private Collection $commentsAuthored;
 
-        /**
-         * Unidirectional - Many-To-One
-         *
-         * @ManyToOne(targetEntity="Comment")
-         */
-        private $firstComment;
+        /** Unidirectional - Many-To-One */
+        #[ManyToOne(targetEntity: Comment::class)]
+        private Comment|null $firstComment;
     }
 
-    /** @Entity */
+    #[Entity]
     class Comment
     {
-        /** @Id @GeneratedValue @Column(type="string") */
-        private $id;
+        #[Id]
+        #[GeneratedValue]
+        #[Column(type: 'string')]
+        private string $id;
 
         /**
          * Bidirectional - Many comments are favorited by many users (INVERSE SIDE)
          *
-         * @ManyToMany(targetEntity="User", mappedBy="favorites")
+         * @var Collection<int, User>
          */
-        private $userFavorites;
+        #[ManyToMany(targetEntity: User::class, mappedBy: 'favorites')]
+        private Collection $userFavorites;
 
         /**
          * Bidirectional - Many Comments are authored by one user (OWNING SIDE)
-         *
-         * @ManyToOne(targetEntity="User", inversedBy="commentsAuthored")
          */
-         private $author;
+        #[ManyToOne(targetEntity: User::class, inversedBy: 'commentsAuthored')]
+        private User|null $author;
     }
 
 This two entities generate the following MySQL Schema (Foreign Key
@@ -132,11 +134,13 @@ relations of the ``User``:
     class User
     {
         // ...
-        public function getReadComments() {
+        /** @return Collection<int, Comment> */
+        public function getReadComments(): Collection {
              return $this->commentsRead;
         }
 
-        public function setFirstComment(Comment $c) {
+        /** @param Collection<int, Comment> $c */
+        public function setFirstComment(Comment $c): void {
             $this->firstComment = $c;
         }
     }
@@ -172,11 +176,13 @@ fields on both sides:
     {
         // ..
 
-        public function getAuthoredComments() {
+        /** @return Collection<int, Comment> */
+        public function getAuthoredComments(): Collection {
             return $this->commentsAuthored;
         }
 
-        public function getFavoriteComments() {
+        /** @return Collection<int, Comment> */
+        public function getFavoriteComments(): Collection {
             return $this->favorites;
         }
     }
@@ -185,11 +191,12 @@ fields on both sides:
     {
         // ...
 
-        public function getUserFavorites() {
+        /** @return Collection<int, User> */
+        public function getUserFavorites(): Collection {
             return $this->userFavorites;
         }
 
-        public function setAuthor(User $author = null) {
+        public function setAuthor(User|null $author = null): void {
             $this->author = $author;
         }
     }
@@ -292,12 +299,12 @@ example that encapsulate much of the association management code:
     class User
     {
         // ...
-        public function markCommentRead(Comment $comment) {
+        public function markCommentRead(Comment $comment): void {
             // Collections implement ArrayAccess
             $this->commentsRead[] = $comment;
         }
 
-        public function addComment(Comment $comment) {
+        public function addComment(Comment $comment): void {
             if (count($this->commentsAuthored) == 0) {
                 $this->setFirstComment($comment);
             }
@@ -305,16 +312,16 @@ example that encapsulate much of the association management code:
             $comment->setAuthor($this);
         }
 
-        private function setFirstComment(Comment $c) {
+        private function setFirstComment(Comment $c): void {
             $this->firstComment = $c;
         }
 
-        public function addFavorite(Comment $comment) {
+        public function addFavorite(Comment $comment): void {
             $this->favorites->add($comment);
             $comment->addUserFavorite($this);
         }
 
-        public function removeFavorite(Comment $comment) {
+        public function removeFavorite(Comment $comment): void {
             $this->favorites->removeElement($comment);
             $comment->removeUserFavorite($this);
         }
@@ -324,11 +331,11 @@ example that encapsulate much of the association management code:
     {
         // ..
 
-        public function addUserFavorite(User $user) {
+        public function addUserFavorite(User $user): void {
             $this->userFavorites[] = $user;
         }
 
-        public function removeUserFavorite(User $user) {
+        public function removeUserFavorite(User $user): void {
             $this->userFavorites->removeElement($user);
         }
     }
@@ -356,7 +363,8 @@ the details inside the classes can be challenging.
 
     <?php
     class User {
-        public function getReadComments() {
+        /** @return array<int, Comment> */
+        public function getReadComments(): array {
             return $this->commentsRead->toArray();
         }
     }
@@ -437,8 +445,10 @@ only accessing it through the User entity:
     // User entity
     class User
     {
-        private $id;
-        private $comments;
+        private int $id;
+
+        /** @var Collection<int, Comment> */
+        private Collection $comments;
 
         public function __construct()
         {
@@ -464,11 +474,8 @@ If you then set up the cascading to the ``User#commentsAuthored`` property...
     class User
     {
         // ...
-        /**
-         * Bidirectional - One-To-Many (INVERSE SIDE)
-         *
-         * @OneToMany(targetEntity="Comment", mappedBy="author", cascade={"persist", "remove"})
-         */
+        /** Bidirectional - One-To-Many (INVERSE SIDE) */
+        #[OneToMany(targetEntity: Comment::class, mappedBy: 'author', cascade: ['persist', 'remove'])]
         private $commentsAuthored;
         // ...
     }
@@ -577,31 +584,30 @@ and StandingData:
 
     use Doctrine\Common\Collections\ArrayCollection;
 
-    /**
-     * @Entity
-     */
+    #[Entity]
     class Contact
     {
-        /** @Id @Column(type="integer") @GeneratedValue */
-        private $id;
+        #[Id, Column(type: 'integer'), GeneratedValue]
+        private int|null $id;
 
-        /** @OneToOne(targetEntity="StandingData", cascade={"persist"}, orphanRemoval=true) */
-        private $standingData;
+        #[OneToOne(targetEntity: StandingData::class, cascade: ['persist'], orphanRemoval: true)]
+        private StandingData|null $standingData;
 
-        /** @OneToMany(targetEntity="Address", mappedBy="contact",  cascade={"persist"}, orphanRemoval=true) */
-        private $addresses;
+        /** @var Collection<int, Address> */
+        #[OneToMany(targetEntity: Address::class, mappedBy: 'contact', cascade: ['persist'], orphanRemoval: true)]
+        private Collection $addresses;
 
         public function __construct()
         {
             $this->addresses = new ArrayCollection();
         }
 
-        public function newStandingData(StandingData $sd)
+        public function newStandingData(StandingData $sd): void
         {
             $this->standingData = $sd;
         }
 
-        public function removeAddress($pos)
+        public function removeAddress(int $pos): void
         {
             unset($this->addresses[$pos]);
         }
diff --git a/docs/en/tutorials/composite-primary-keys.rst b/docs/en/tutorials/composite-primary-keys.rst
index 12ad55e53bb..9aaae10c06a 100644
--- a/docs/en/tutorials/composite-primary-keys.rst
+++ b/docs/en/tutorials/composite-primary-keys.rst
@@ -23,33 +23,28 @@ and year of production as primary keys:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
 
         <?php
         namespace VehicleCatalogue\Model;
 
-        /**
-         * @Entity
-         */
+        #[Entity]
         class Car
         {
-            /** @Id @Column(type="string") */
-            private $name;
-            /** @Id @Column(type="integer") */
-            private $year;
-
-            public function __construct($name, $year)
-            {
-                $this->name = $name;
-                $this->year = $year;
+            public function __construct(
+                #[Id, Column(type="string")]
+                string $name,
+                #[Id, Column(type="integer")]
+                int $year,
+            ) {
             }
 
-            public function getModelName()
+            public function getModelName(): string
             {
                 return $this->name;
             }
 
-            public function getYearOfProduction()
+            public function getYearOfProduction(): int
             {
                 return $this->year;
             }