From e97c1f3f44b502ca615f6076ac4d6010ea088fe8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gr=C3=A9goire=20Paris?= <postmaster@greg0ire.fr>
Date: Wed, 19 Oct 2022 21:10:55 +0200
Subject: [PATCH] Restore annotations blocks

They are not officially deprecated yet, and even then, can be useful
documentation.
---
 docs/en/reference/association-mapping.rst     | 339 +++++++++++++++++-
 docs/en/reference/basic-mapping.rst           |  28 ++
 docs/en/reference/events.rst                  |  37 +-
 docs/en/reference/inheritance-mapping.rst     | 127 ++++++-
 docs/en/reference/second-level-cache.rst      |  66 +++-
 .../transactions-and-concurrency.rst          |  26 +-
 docs/en/tutorials/composite-primary-keys.rst  | 106 +++++-
 docs/en/tutorials/embeddables.rst             |  57 ++-
 docs/en/tutorials/extra-lazy-associations.rst |  19 +-
 docs/en/tutorials/getting-started.rst         | 144 +++++++-
 docs/en/tutorials/ordered-associations.rst    |  16 +
 .../working-with-indexed-associations.rst     | 113 +++++-
 12 files changed, 1043 insertions(+), 35 deletions(-)

diff --git a/docs/en/reference/association-mapping.rst b/docs/en/reference/association-mapping.rst
index fd760866e15..9b1257f411e 100644
--- a/docs/en/reference/association-mapping.rst
+++ b/docs/en/reference/association-mapping.rst
@@ -37,7 +37,28 @@ A many-to-one association is the most common association between objects. Exampl
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        /** @Entity */
+        class User
+        {
+            // ...
+
+            /**
+             * @ManyToOne(targetEntity="Address")
+             * @JoinColumn(name="address_id", referencedColumnName="id")
+             */
+            private Address|null $address = null;
+        }
+
+        /** @Entity */
+        class Address
+        {
+            // ...
+        }
+
+    .. code-block:: attribute
 
         <?php
         #[Entity]
@@ -111,7 +132,31 @@ references one ``Shipment`` entity.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        /** @Entity */
+        class Product
+        {
+            // ...
+
+            /**
+             * One Product has One Shipment.
+             * @OneToOne(targetEntity="Shipment")
+             * @JoinColumn(name="shipment_id", referencedColumnName="id")
+             */
+            private Shipment|null $shipment = null;
+
+            // ...
+        }
+
+        /** @Entity */
+        class Shipment
+        {
+            // ...
+        }
+
+    .. code-block:: attribute
 
         <?php
         #[Entity]
@@ -186,7 +231,39 @@ object.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        /** @Entity */
+        class Customer
+        {
+            // ...
+
+            /**
+             * One Customer has One Cart.
+             * @OneToOne(targetEntity="Cart", mappedBy="customer")
+             */
+            private Cart|null $cart = null;
+
+            // ...
+        }
+
+        /** @Entity */
+        class Cart
+        {
+            // ...
+
+            /**
+             * One Cart has One Customer.
+             * @OneToOne(targetEntity="Customer", inversedBy="cart")
+             * @JoinColumn(name="customer_id", referencedColumnName="id")
+             */
+            private Customer|null $customer = null;
+
+            // ...
+        }
+
+    .. code-block:: attribute
 
         <?php
         #[Entity]
@@ -318,7 +395,42 @@ bidirectional many-to-one.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        use Doctrine\Common\Collections\ArrayCollection;
+
+        /** @Entity */
+        class Product
+        {
+            // ...
+            /**
+             * One product has many features. This is the inverse side.
+             * @var Collection<int, Feature>
+             * @OneToMany(targetEntity="Feature", mappedBy="product")
+             */
+            private Collection $features;
+            // ...
+
+            public function __construct() {
+                $this->features = new ArrayCollection();
+            }
+        }
+
+        /** @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|null $product = null;
+            // ...
+        }
+
+    .. code-block:: attribute
 
         <?php
         use Doctrine\Common\Collections\ArrayCollection;
@@ -412,7 +524,40 @@ The following example sets up such a unidirectional one-to-many association:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        /** @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 Collection $phonenumbers;
+
+            public function __construct()
+            {
+                $this->phonenumbers = new \Doctrine\Common\Collections\ArrayCollection();
+            }
+
+            // ...
+        }
+
+        /** @Entity */
+        class Phonenumber
+        {
+            // ...
+        }
+
+    .. code-block:: attribute
 
         <?php
         #[Entity]
@@ -514,7 +659,34 @@ database perspective is known as an adjacency list approach.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        /** @Entity */
+        class Category
+        {
+            // ...
+            /**
+             * One Category has Many Categories.
+             * @OneToMany(targetEntity="Category", mappedBy="parent")
+             * @var Collection<int, Category>
+             */
+            private Collection $children;
+
+            /**
+             * Many Categories have One Category.
+             * @ManyToOne(targetEntity="Category", inversedBy="children")
+             * @JoinColumn(name="parent_id", referencedColumnName="id")
+             */
+            private Category|null $parent = null;
+            // ...
+
+            public function __construct() {
+                $this->children = new \Doctrine\Common\Collections\ArrayCollection();
+            }
+        }
+
+    .. code-block:: attribute
 
         <?php
         #[Entity]
@@ -584,7 +756,39 @@ entities:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        /** @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 Collection $groups;
+
+            // ...
+
+            public function __construct() {
+                $this->groups = new \Doctrine\Common\Collections\ArrayCollection();
+            }
+        }
+
+        /** @Entity */
+        class Group
+        {
+            // ...
+        }
+
+    .. code-block:: attribute
 
         <?php
         #[Entity]
@@ -685,7 +889,48 @@ one is bidirectional.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        /** @Entity */
+        class User
+        {
+            // ...
+
+            /**
+             * Many Users have Many Groups.
+             * @ManyToMany(targetEntity="Group", inversedBy="users")
+             * @JoinTable(name="users_groups")
+             * @var Collection<int, Group>
+             */
+            private Collection $groups;
+
+            public function __construct() {
+                $this->groups = new \Doctrine\Common\Collections\ArrayCollection();
+            }
+
+            // ...
+        }
+
+        /** @Entity */
+        class Group
+        {
+            // ...
+            /**
+             * Many Groups have Many Users.
+             * @ManyToMany(targetEntity="User", mappedBy="groups")
+             * @var Collection<int, User>
+             */
+            private Collection $users;
+
+            public function __construct() {
+                $this->users = new \Doctrine\Common\Collections\ArrayCollection();
+            }
+
+            // ...
+        }
+
+    .. code-block:: attribute
 
         <?php
         #[Entity]
@@ -903,7 +1148,13 @@ As an example, consider this mapping:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        /** @OneToOne(targetEntity="Shipment") */
+        private Shipment|null $shipment = null;
+
+    .. code-block:: attribute
 
         <?php
         #[OneToOne(targetEntity: Shipment::class)]
@@ -930,7 +1181,17 @@ mapping:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        /**
+         * One Product has One Shipment.
+         * @OneToOne(targetEntity="Shipment")
+         * @JoinColumn(name="shipment_id", referencedColumnName="id")
+         */
+        private Shipment|null $shipment = null;
+
+    .. code-block:: attribute
 
         <?php
         /** One Product has One Shipment. */
@@ -964,12 +1225,27 @@ similar defaults. As an example, consider this mapping:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
 
         <?php
         class User
         {
             // ...
+            /**
+             * @ManyToMany(targetEntity="Group")
+             * @var Collection<int, Group>
+             */
+            private Collection $groups;
+            // ...
+        }
+
+    .. code-block:: attribute
+
+        <?php
+        class User
+        {
+            // ...
+            /** @var Collection<int, Group> */
             #[ManyToMany(targetEntity: Group::class)]
             private Collection $groups;
             // ...
@@ -995,7 +1271,26 @@ This is essentially the same as the following, more verbose, mapping:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        class User
+        {
+            // ...
+            /**
+             * 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 Collection $groups;
+            // ...
+        }
+
+    .. code-block:: attribute
 
         <?php
         class User
@@ -1060,7 +1355,13 @@ attribute on ``JoinColumn`` will be inherited from PHP type. So that:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        /** @OneToOne */
+        private Shipment $shipment;
+
+    .. code-block:: attribute
 
         <?php
         #[OneToOne]
@@ -1085,7 +1386,17 @@ Is essentially the same as following:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        /**
+         * One Product has One Shipment.
+         * @OneToOne(targetEntity="Shipment")
+         * @JoinColumn(name="shipment_id", referencedColumnName="id", nullable=false)
+         */
+        private Shipment $shipment;
+
+    .. code-block:: attribute
 
         <?php
         /** One Product has One Shipment. */
diff --git a/docs/en/reference/basic-mapping.rst b/docs/en/reference/basic-mapping.rst
index 7dd181d1460..84094f7bcd0 100644
--- a/docs/en/reference/basic-mapping.rst
+++ b/docs/en/reference/basic-mapping.rst
@@ -365,6 +365,20 @@ the field that serves as the identifier with the ``#[Id]`` attribute.
 
 .. configuration-block::
 
+    .. code-block:: annotation
+
+        <?php
+        class Message
+        {
+            /**
+             * @Id
+             * @Column(type="integer")
+             * @GeneratedValue
+             */
+            private int|null $id = null;
+            // ...
+        }
+
     .. code-block:: attribute
 
         <?php
@@ -449,6 +463,20 @@ besides specifying the sequence's name:
 
 .. configuration-block::
 
+    .. code-block:: annotation
+
+        <?php
+        class Message
+        {
+            /**
+             * @Id
+             * @GeneratedValue(strategy="SEQUENCE")
+             * @SequenceGenerator(sequenceName="message_seq", initialValue=1, allocationSize=100)
+             */
+            protected int|null $id = null;
+            // ...
+        }
+
     .. code-block:: attribute
 
         <?php
diff --git a/docs/en/reference/events.rst b/docs/en/reference/events.rst
index 6255f4f6f72..b6e872a7214 100644
--- a/docs/en/reference/events.rst
+++ b/docs/en/reference/events.rst
@@ -827,7 +827,7 @@ you need to map the listener method using the event type mapping:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
 
         <?php
         use Doctrine\ORM\Event\PreUpdateEventArgs;
@@ -860,6 +860,41 @@ you need to map the listener method using the event type mapping:
             /** @PostLoad */
             public function postLoadHandler(User $user, LifecycleEventArgs $event) { // ... }
         }
+
+    .. code-block:: attribute
+
+        <?php
+        use Doctrine\ORM\Event\PreUpdateEventArgs;
+        use Doctrine\ORM\Event\PreFlushEventArgs;
+        use Doctrine\Persistence\Event\LifecycleEventArgs;
+
+        class UserListener
+        {
+            #[PrePersist]
+            public function prePersistHandler(User $user, LifecycleEventArgs $event) { // ... }
+
+            #[PostPersist]
+            public function postPersistHandler(User $user, LifecycleEventArgs $event) { // ... }
+
+            #[PreUpdate]
+            public function preUpdateHandler(User $user, PreUpdateEventArgs $event) { // ... }
+
+            #[PostUpdate]
+            public function postUpdateHandler(User $user, LifecycleEventArgs $event) { // ... }
+
+            #[PostRemove]
+            public function postRemoveHandler(User $user, LifecycleEventArgs $event) { // ... }
+
+            #[PreRemove]
+            public function preRemoveHandler(User $user, LifecycleEventArgs $event) { // ... }
+
+            #[PreFlush]
+            public function preFlushHandler(User $user, PreFlushEventArgs $event) { // ... }
+
+            #[PostLoad]
+            public function postLoadHandler(User $user, LifecycleEventArgs $event) { // ... }
+        }
+
     .. code-block:: xml
 
         <doctrine-mapping>
diff --git a/docs/en/reference/inheritance-mapping.rst b/docs/en/reference/inheritance-mapping.rst
index 183769a9b02..00f1a9dd461 100644
--- a/docs/en/reference/inheritance-mapping.rst
+++ b/docs/en/reference/inheritance-mapping.rst
@@ -97,7 +97,31 @@ Example:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        namespace MyProject\Model;
+
+        /**
+         * @Entity
+         * @InheritanceType("SINGLE_TABLE")
+         * @DiscriminatorColumn(name="discr", type="string")
+         * @DiscriminatorMap({"person" = "Person", "employee" = "Employee"})
+         */
+        class Person
+        {
+            // ...
+        }
+
+        /**
+         * @Entity
+         */
+        class Employee extends Person
+        {
+            // ...
+        }
+
+    .. code-block:: attribute
 
         <?php
         namespace MyProject\Model;
@@ -323,7 +347,59 @@ Example:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        // user mapping
+        namespace MyProject\Model;
+        /**
+         * @MappedSuperclass
+         */
+        class User
+        {
+            // other fields mapping
+
+            /**
+             * @ManyToMany(targetEntity="Group", inversedBy="users")
+             * @JoinTable(name="users_groups",
+             *  joinColumns={@JoinColumn(name="user_id", referencedColumnName="id")},
+             *  inverseJoinColumns={@JoinColumn(name="group_id", referencedColumnName="id")}
+             * )
+             * @var Collection<int, Group>
+             */
+            protected Collection $groups;
+
+            /**
+             * @ManyToOne(targetEntity="Address")
+             * @JoinColumn(name="address_id", referencedColumnName="id")
+             */
+            protected Address|null $address = null;
+        }
+
+        // admin mapping
+        namespace MyProject\Model;
+        /**
+         * @Entity
+         * @AssociationOverrides({
+         *      @AssociationOverride(name="groups",
+         *          joinTable=@JoinTable(
+         *              name="users_admingroups",
+         *              joinColumns=@JoinColumn(name="adminuser_id"),
+         *              inverseJoinColumns=@JoinColumn(name="admingroup_id")
+         *          )
+         *      ),
+         *      @AssociationOverride(name="address",
+         *          joinColumns=@JoinColumn(
+         *              name="adminaddress_id", referencedColumnName="id"
+         *          )
+         *      )
+         * })
+         */
+        class Admin extends User
+        {
+        }
+
+    .. code-block:: attribute
 
         <?php
         // user mapping
@@ -477,7 +553,52 @@ Could be used by an entity that extends a mapped superclass to override a field
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        // user mapping
+        namespace MyProject\Model;
+        /**
+         * @MappedSuperclass
+         */
+        class User
+        {
+            /** @Id @GeneratedValue @Column(type="integer", name="user_id", length=150) */
+            protected int|null $id = null;
+
+            /** @Column(name="user_name", nullable=true, unique=false, length=250) */
+            protected string $name;
+
+            // other fields mapping
+        }
+
+        // guest mapping
+        namespace MyProject\Model;
+        /**
+         * @Entity
+         * @AttributeOverrides({
+         *      @AttributeOverride(name="id",
+         *          column=@Column(
+         *              name     = "guest_id",
+         *              type     = "integer",
+         *              length   = 140
+         *          )
+         *      ),
+         *      @AttributeOverride(name="name",
+         *          column=@Column(
+         *              name     = "guest_name",
+         *              nullable = false,
+         *              unique   = true,
+         *              length   = 240
+         *          )
+         *      )
+         * })
+         */
+        class Guest extends User
+        {
+        }
+
+    .. code-block:: attribute
 
         <?php
         // user mapping
diff --git a/docs/en/reference/second-level-cache.rst b/docs/en/reference/second-level-cache.rst
index a589fec7958..b9d40523c3f 100644
--- a/docs/en/reference/second-level-cache.rst
+++ b/docs/en/reference/second-level-cache.rst
@@ -277,7 +277,31 @@ level cache region.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        /**
+         * @Entity
+         * @Cache("NONSTRICT_READ_WRITE")
+         */
+        class State
+        {
+            /**
+             * @Id
+             * @GeneratedValue
+             * @Column(type="integer")
+             */
+            protected int|null $id = null;
+
+            /**
+             * @Column(unique=true)
+             */
+            protected string $name;
+
+            // other properties and methods
+        }
+
+    .. code-block:: attribute
 
         <?php
         #[Entity]
@@ -334,7 +358,45 @@ It caches the primary keys of association and cache each element will be cached
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        /**
+         * @Entity
+         * @Cache("NONSTRICT_READ_WRITE")
+         */
+        class State
+        {
+            /**
+             * @Id
+             * @GeneratedValue
+             * @Column(type="integer")
+             */
+            protected int|null $id = null;
+
+            /**
+             * @Column(unique=true)
+             */
+            protected string $name;
+
+            /**
+             * @Cache("NONSTRICT_READ_WRITE")
+             * @ManyToOne(targetEntity="Country")
+             * @JoinColumn(name="country_id", referencedColumnName="id")
+             */
+            protected Country|null $country;
+
+            /**
+             * @Cache("NONSTRICT_READ_WRITE")
+             * @OneToMany(targetEntity="City", mappedBy="state")
+             * @var Collection<int, City>
+             */
+            protected Collection $cities;
+
+            // other properties and methods
+        }
+
+    .. code-block:: attribute
 
         <?php
         #[Entity]
diff --git a/docs/en/reference/transactions-and-concurrency.rst b/docs/en/reference/transactions-and-concurrency.rst
index e57d3d84842..b6cffffe480 100644
--- a/docs/en/reference/transactions-and-concurrency.rst
+++ b/docs/en/reference/transactions-and-concurrency.rst
@@ -189,7 +189,18 @@ example we'll use an integer.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        class User
+        {
+            // ...
+            /** @Version @Column(type="integer") */
+            private int $version;
+            // ...
+        }
+
+    .. code-block:: attribute
 
         <?php
         class User
@@ -222,7 +233,18 @@ timestamp or datetime):
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        class User
+        {
+            // ...
+            /** @Version @Column(type="datetime") */
+            private DateTime $version;
+            // ...
+        }
+
+    .. code-block:: attribute
 
         <?php
         class User
diff --git a/docs/en/tutorials/composite-primary-keys.rst b/docs/en/tutorials/composite-primary-keys.rst
index da5b8e90eb1..507109758bb 100644
--- a/docs/en/tutorials/composite-primary-keys.rst
+++ b/docs/en/tutorials/composite-primary-keys.rst
@@ -23,6 +23,38 @@ and year of production as primary keys:
 
 .. configuration-block::
 
+    .. code-block:: annotation
+
+        <?php
+        namespace VehicleCatalogue\Model;
+
+        /**
+         * @Entity
+         */
+        class Car
+        {
+            /** @Id @Column(type="string") */
+            private string $name;
+            /** @Id @Column(type="integer") */
+            private int $year;
+
+            public function __construct($name, $year)
+            {
+                $this->name = $name;
+                $this->year = $year;
+            }
+
+            public function getModelName(): string
+            {
+                return $this->name;
+            }
+
+            public function getYearOfProduction(): int
+            {
+                return $this->year;
+            }
+        }
+
     .. code-block:: attribute
 
         <?php
@@ -144,6 +176,57 @@ We keep up the example of an Article with arbitrary attributes, the mapping look
 
         use Doctrine\Common\Collections\ArrayCollection;
 
+        /**
+         * @Entity
+         */
+        class Article
+        {
+            /** @Id @Column(type="integer") @GeneratedValue */
+            private int|null $id = null;
+            /** @Column(type="string") */
+            private string $title;
+
+            /**
+             * @OneToMany(targetEntity="ArticleAttribute", mappedBy="article", cascade={"ALL"}, indexBy="attribute")
+             * @var Collection<int, ArticleAttribute>
+             */
+            private Collection $attributes;
+
+            public function addAttribute($name, $value): void
+            {
+                $this->attributes[$name] = new ArticleAttribute($name, $value, $this);
+            }
+        }
+
+        /**
+         * @Entity
+         */
+        class ArticleAttribute
+        {
+            /** @Id @ManyToOne(targetEntity="Article", inversedBy="attributes") */
+            private Article|null $article;
+
+            /** @Id @Column(type="string") */
+            private string $attribute;
+
+            /** @Column(type="string") */
+            private string $value;
+
+            public function __construct($name, $value, $article)
+            {
+                $this->attribute = $name;
+                $this->value = $value;
+                $this->article = $article;
+            }
+        }
+
+    .. code-block:: attribute
+
+        <?php
+        namespace Application\Model;
+
+        use Doctrine\Common\Collections\ArrayCollection;
+
         #[Entity]
         class Article
         {
@@ -227,7 +310,28 @@ One good example for this is a user-address relationship:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        /**
+         * @Entity
+         */
+        class User
+        {
+            /** @Id @Column(type="integer") @GeneratedValue */
+            private int|null $id = null;
+        }
+
+        /**
+         * @Entity
+         */
+        class Address
+        {
+            /** @Id @OneToOne(targetEntity="User") */
+            private User|null $user = null;
+        }
+
+    .. code-block:: attribute
 
         <?php
 
diff --git a/docs/en/tutorials/embeddables.rst b/docs/en/tutorials/embeddables.rst
index 0ea63c04f48..572b8263cf0 100644
--- a/docs/en/tutorials/embeddables.rst
+++ b/docs/en/tutorials/embeddables.rst
@@ -17,7 +17,34 @@ instead of simply adding the respective columns to the ``User`` class.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+
+        /** @Entity */
+        class User
+        {
+            /** @Embedded(class = "Address") */
+            private Address $address;
+        }
+
+        /** @Embeddable */
+        class Address
+        {
+            /** @Column(type = "string") */
+            private string $street;
+
+            /** @Column(type = "string") */
+            private string $postalCode;
+
+            /** @Column(type = "string") */
+            private string $city;
+
+            /** @Column(type = "string") */
+            private string $country;
+        }
+
+    .. code-block:: attribute
 
         <?php
 
@@ -109,7 +136,18 @@ The following example shows you how to set your prefix to ``myPrefix_``:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+
+        /** @Entity */
+        class User
+        {
+            /** @Embedded(class = "Address", columnPrefix = "myPrefix_") */
+            private $address;
+        }
+
+    .. code-block:: attribute
 
         <?php
 
@@ -140,7 +178,18 @@ directly, set ``columnPrefix=false`` (``use-column-prefix="false"`` for XML):
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+
+        /** @Entity */
+        class User
+        {
+            /** @Embedded(class = "Address", columnPrefix = false) */
+            private Address $address;
+        }
+
+    .. code-block:: attribute
 
         <?php
 
@@ -148,7 +197,7 @@ directly, set ``columnPrefix=false`` (``use-column-prefix="false"`` for XML):
         class User
         {
             #[Embedded(class: Address::class, columnPrefix: false)]
-            private $address;
+            private Address $address;
         }
 
     .. code-block:: xml
diff --git a/docs/en/tutorials/extra-lazy-associations.rst b/docs/en/tutorials/extra-lazy-associations.rst
index ab58454fedf..03d4561eede 100644
--- a/docs/en/tutorials/extra-lazy-associations.rst
+++ b/docs/en/tutorials/extra-lazy-associations.rst
@@ -52,7 +52,24 @@ switch to extra lazy as shown in these examples:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        namespace Doctrine\Tests\Models\CMS;
+
+        /**
+         * @Entity
+         */
+        class CmsGroup
+        {
+            /**
+             * @ManyToMany(targetEntity="CmsUser", mappedBy="groups", fetch="EXTRA_LAZY")
+             * @var Collection<int, CmsUser>
+             */
+            public Collection $users;
+        }
+
+    .. code-block:: attribute
 
         <?php
         namespace Doctrine\Tests\Models\CMS;
diff --git a/docs/en/tutorials/getting-started.rst b/docs/en/tutorials/getting-started.rst
index 50c28263b3e..0f29779809c 100644
--- a/docs/en/tutorials/getting-started.rst
+++ b/docs/en/tutorials/getting-started.rst
@@ -495,7 +495,34 @@ methods, but you only need to choose one.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        // src/Product.php
+
+        use Doctrine\ORM\Mapping as ORM;
+
+        /**
+         * @ORM\Entity
+         * @ORM\Table(name="products")
+         */
+        class Product
+        {
+            /**
+             * @ORM\Id
+             * @ORM\Column(type="integer")
+             * @ORM\GeneratedValue
+             */
+            private int|null $id = null;
+            /**
+             * @ORM\Column(type="string")
+             */
+            private string $name;
+
+            // .. (other code)
+        }
+
+    .. code-block:: attribute
 
         <?php
         // src/Product.php
@@ -1017,7 +1044,60 @@ Lets add metadata mappings for the ``Bug`` entity, as we did for
 the ``Product`` before:
 
 .. configuration-block::
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        // src/Bug.php
+
+        use Doctrine\ORM\Mapping as ORM;
+
+        /**
+         * @ORM\Entity
+         * @ORM\Table(name="bugs")
+         */
+        class Bug
+        {
+            /**
+             * @ORM\Id
+             * @ORM\Column(type="integer")
+             * @ORM\GeneratedValue
+             */
+            private int|null $id = null;
+
+            /**
+             * @ORM\Column(type="string")
+             */
+            private string $description;
+
+            /**
+             * @ORM\Column(type="datetime")
+             */
+            private DateTime $created;
+
+            /**
+             * @ORM\Column(type="string")
+             */
+            private string $status;
+
+            /**
+             * @ORM\ManyToOne(targetEntity="User", inversedBy="assignedBugs")
+             */
+            private User|null $engineer;
+
+            /**
+             * @ORM\ManyToOne(targetEntity="User", inversedBy="reportedBugs")
+             */
+            private User|null $reporter;
+
+            /**
+             * @ORM\ManyToMany(targetEntity="Product")
+             */
+            private Collection $products;
+
+            // ... (other code)
+        }
+
+    .. code-block:: attribute
 
         <?php
         // src/Bug.php
@@ -1140,7 +1220,48 @@ Finally, we'll add metadata mappings for the ``User`` entity.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        // src/User.php
+
+        use Doctrine\ORM\Mapping as ORM;
+
+        /**
+         * @ORM\Entity
+         * @ORM\Table(name="users")
+         */
+        class User
+        {
+            /**
+             * @ORM\Id
+             * @ORM\GeneratedValue
+             * @ORM\Column(type="integer")
+             * @var int
+             */
+            private int|null $id = null;
+
+            /**
+             * @ORM\Column(type="string")
+             * @var string
+             */
+            private string $name;
+
+            /**
+             * @ORM\OneToMany(targetEntity="Bug", mappedBy="reporter")
+             * @var Collection<int, Bug> An ArrayCollection of Bug objects.
+             */
+            private Collection $reportedBugs;
+
+            /**
+             * @ORM\OneToMany(targetEntity="Bug", mappedBy="engineer")
+             * @var Collection<int, Bug> An ArrayCollection of Bug objects.
+             */
+            private Collection $assignedBugs;
+
+            // .. (other code)
+        }
+    .. code-block:: attribute
 
         <?php
         // src/User.php
@@ -1699,7 +1820,7 @@ we have to adjust the metadata slightly.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: annotation
 
         <?php
 
@@ -1708,7 +1829,20 @@ we have to adjust the metadata slightly.
         /**
          * @ORM\Entity(repositoryClass="BugRepository")
          * @ORM\Table(name="bugs")
-         **/
+         */
+        class Bug
+        {
+            // ...
+        }
+
+    .. code-block:: attribute
+
+        <?php
+
+        use Doctrine\ORM\Mapping as ORM;
+
+        #[ORM\Entity(repositoryClass: BugRepository::class)]
+        #[ORM\Table(name: 'bugs')]
         class Bug
         {
             // ...
diff --git a/docs/en/tutorials/ordered-associations.rst b/docs/en/tutorials/ordered-associations.rst
index 930b3d9df56..a4ca8a408c9 100644
--- a/docs/en/tutorials/ordered-associations.rst
+++ b/docs/en/tutorials/ordered-associations.rst
@@ -14,6 +14,22 @@ can specify the ``#[OrderBy]`` in the following way:
 
 .. configuration-block::
 
+    .. code-block:: annotation
+
+        <?php
+        /** @Entity **/
+        class User
+        {
+            // ...
+
+            /**
+             * @ManyToMany(targetEntity="Group")
+             * @OrderBy({"name" = "ASC"})
+             * @var Collection<int, Group>
+             */
+            private Collection $groups;
+        }
+
     .. code-block:: attribute
 
         <?php
diff --git a/docs/en/tutorials/working-with-indexed-associations.rst b/docs/en/tutorials/working-with-indexed-associations.rst
index 9988069b119..33fba410b7b 100644
--- a/docs/en/tutorials/working-with-indexed-associations.rst
+++ b/docs/en/tutorials/working-with-indexed-associations.rst
@@ -31,7 +31,75 @@ You can map indexed associations by adding:
 The code and mappings for the Market entity looks like this:
 
 .. configuration-block::
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        namespace Doctrine\Tests\Models\StockExchange;
+
+        use Doctrine\Common\Collections\ArrayCollection;
+
+        /**
+         * @Entity
+         * @Table(name="exchange_markets")
+         */
+        class Market
+        {
+            /**
+             * @Id @Column(type="integer") @GeneratedValue
+             * @var int
+             */
+            private int|null $id = null;
+
+            /**
+             * @Column(type="string")
+             * @var string
+             */
+            private string $name;
+
+            /**
+             * @OneToMany(targetEntity="Stock", mappedBy="market", indexBy="symbol")
+             * @var Collection<int, Stock>
+             */
+            private Collection $stocks;
+
+            public function __construct($name)
+            {
+                $this->name = $name;
+                $this->stocks = new ArrayCollection();
+            }
+
+            public function getId(): int|null
+            {
+                return $this->id;
+            }
+
+            public function getName(): string
+            {
+                return $this->name;
+            }
+
+            public function addStock(Stock $stock): void
+            {
+                $this->stocks[$stock->getSymbol()] = $stock;
+            }
+
+            public function getStock($symbol): Stock
+            {
+                if (!isset($this->stocks[$symbol])) {
+                    throw new \InvalidArgumentException("Symbol is not traded on this market.");
+                }
+
+                return $this->stocks[$symbol];
+            }
+
+            /** @return array<string, Stock> */
+            public function getStocks(): array
+            {
+                return $this->stocks->toArray();
+            }
+        }
+
+    .. code-block:: attribute
 
         <?php
         namespace Doctrine\Tests\Models\StockExchange;
@@ -135,7 +203,48 @@ The ``Stock`` entity doesn't contain any special instructions that are new, but
 here are the code and mappings for it:
 
 .. configuration-block::
-    .. code-block:: php
+    .. code-block:: annotation
+
+        <?php
+        namespace Doctrine\Tests\Models\StockExchange;
+
+        /**
+         * @Entity
+         * @Table(name="exchange_stocks")
+         */
+        class Stock
+        {
+            /**
+             * @Id @GeneratedValue @Column(type="integer")
+             * @var int
+             */
+            private int|null $id = null;
+
+            /**
+             * @Column(type="string", unique=true)
+             */
+            private string $symbol;
+
+            /**
+             * @ManyToOne(targetEntity="Market", inversedBy="stocks")
+             * @var Market
+             */
+            private Market|null $market = null;
+
+            public function __construct($symbol, Market $market)
+            {
+                $this->symbol = $symbol;
+                $this->market = $market;
+                $market->addStock($this);
+            }
+
+            public function getSymbol(): string
+            {
+                return $this->symbol;
+            }
+        }
+
+    .. code-block:: attribute
 
         <?php
         namespace Doctrine\Tests\Models\StockExchange;