Restore annotations blocks

They are not officially deprecated yet, and even then, can be useful
documentation.

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

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>

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

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]

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