Migrate more documentation towards attributes #10157

greg0ire · 2022-10-19T14:05:37Z

The previous rework missed some details / left the documentation in an inconsistent state. Searching for "annotation" case insensitively allows to find discrepancies and forgotten things.

greg0ire · 2022-10-19T19:41:47Z

I also added another commit to address @stof 's comment

stof · 2022-10-21T07:53:20Z

docs/en/cookbook/strategy-cookbook-introduction.rst

@@ -154,7 +154,7 @@ As you can see, we have a method "setBlockEntity" which ties a potential strateg
         * This var contains the classname of the strategy
         * that is used for this blockitem. (This string (!) value will be persisted by Doctrine ORM)
         *
-         * This is a doctrine field, so make sure that you use an @column annotation or setup your
+         * This is a doctrine field, so make sure that you use an @[Column] attribute or setup your


should not be a @ here

stof · 2022-10-21T07:55:09Z

docs/en/cookbook/validation-of-entities.rst

@@ -53,20 +53,17 @@ code, enforcing it at any time is important so that customers with
 a unknown reputation don't owe your business too much money.

 We can enforce this constraint in any of the metadata drivers.
-First Annotations:
+First Attributes:


the doc below shows other formats. So maybe it should keep annotations as well.

And for Yaml, there is a sentence saying this will happen before Beta 1 though which looks totally wrong in the doc (and it does not say beta 1 of which version)

stof · 2022-10-21T07:58:52Z

docs/en/reference/advanced-configuration.rst

@@ -124,18 +125,18 @@ used in the examples. For information on the usage of the
 AnnotationDriver, XmlDriver or YamlDriver please refer to the dedicated
 chapters ``Annotation Reference``, ``XML Mapping`` and ``YAML Mapping``.

-The annotation driver can be configured with a factory method on
+The attribute driver can be configured with a factory method on


there is no factory method (and before, it was not on the Configuration class)

stof · 2022-10-21T07:59:55Z

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


I would put attribute before annotation, as attribute is the default in the docs

stof · 2022-10-21T08:05:43Z

docs/en/reference/basic-mapping.rst

@@ -437,7 +451,7 @@ Here is the list of possible generation strategies:
   thus generated) by your code. The assignment must take place before
   a new entity is passed to ``EntityManager#persist``. NONE is the
   same as leaving off the @GeneratedValue entirely.


@GeneratedValue should be replaced too, meaning the attribute instead

stof · 2022-10-21T08:08:58Z

docs/en/tutorials/getting-started.rst

+    $config = ORMSetup::createAttributeMetadataConfiguration(
+        paths: array(__DIR__."/src"),
+        isDevMode: true,
+    );
    // or if you prefer YAML or XML


should we have a or if you prefer annotation ?

derrabus · 2022-10-21T08:30:54Z

docs/en/cookbook/advanced-field-value-conversion-using-custom-mapping-types.rst

-            $this->longitude = $longitude;
+        public function __construct(
+            private float $latitude,
+            private float$longitude,


Suggested change

private float$longitude,

private float $longitude,

derrabus · 2022-10-21T08:31:29Z

docs/en/cookbook/strategy-cookbook-introduction.rst

@@ -154,7 +154,7 @@ As you can see, we have a method "setBlockEntity" which ties a potential strateg
         * This var contains the classname of the strategy
         * that is used for this blockitem. (This string (!) value will be persisted by Doctrine ORM)
         *
-         * This is a doctrine field, so make sure that you use an @column annotation or setup your
+         * This is a doctrine field, so make sure that you use an @[Column] attribute or setup your


Suggested change

* This is a doctrine field, so make sure that you use an @[Column] attribute or setup your

* This is a doctrine field, so make sure that you use an #[Column] attribute or setup your

derrabus · 2022-10-21T08:32:06Z

docs/en/cookbook/advanced-field-value-conversion-using-custom-mapping-types.rst

+        #[Column(type: 'point')]
+        private Point $point;
+
+        #[Column()]


Suggested change

#[Column()]

#[Column]

derrabus · 2022-10-21T08:34:26Z

docs/en/reference/events.rst

+        class UserListener
+        {
+            #[PrePersist]
+            public function prePersistHandler(User $user, LifecycleEventArgs $event) { // ... }


Shall we make the return type explicit to indicate that we don't expect the listener to return anything?

Suggested change

public function prePersistHandler(User $user, LifecycleEventArgs $event) { // ... }

public function prePersistHandler(User $user, LifecycleEventArgs $event): void { // ... }

The previous rework missed some details / left the documentation in an inconsistent state. Searching for "annotation" case insensitively allows to find discrepancies and forgotten things.

greg0ire requested review from SenseException and derrabus October 19, 2022 14:05

greg0ire added the Documentation label Oct 19, 2022

greg0ire force-pushed the followup-migrate-docs-to-attributes branch from 151f0c7 to 82ffb64 Compare October 19, 2022 14:13

greg0ire mentioned this pull request Oct 19, 2022

Modernize documentation code #10126

Merged

greg0ire requested a review from stof October 20, 2022 19:10

stof reviewed Oct 21, 2022

View reviewed changes

derrabus requested changes Oct 21, 2022

View reviewed changes

greg0ire and others added 2 commits October 21, 2022 12:31

Remove wrong sentence

d79e61f

Migrate more documentation towards attributes

4e445fe

The previous rework missed some details / left the documentation in an inconsistent state. Searching for "annotation" case insensitively allows to find discrepancies and forgotten things.

greg0ire force-pushed the followup-migrate-docs-to-attributes branch from e97c1f3 to 4e445fe Compare October 21, 2022 10:31

greg0ire requested review from derrabus and stof October 21, 2022 10:32

derrabus approved these changes Oct 21, 2022

View reviewed changes

derrabus added this to the 2.13.4 milestone Oct 21, 2022

greg0ire merged commit 9f926f0 into doctrine:2.13.x Oct 21, 2022

greg0ire deleted the followup-migrate-docs-to-attributes branch October 21, 2022 19:25

greg0ire mentioned this pull request Jan 3, 2023

Docs: Deleting duplicate mapping example #10363

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migrate more documentation towards attributes #10157

Migrate more documentation towards attributes #10157

greg0ire commented Oct 19, 2022

greg0ire commented Oct 19, 2022

stof Oct 21, 2022

stof Oct 21, 2022

stof Oct 21, 2022

stof Oct 21, 2022

stof Oct 21, 2022

stof Oct 21, 2022

derrabus Oct 21, 2022

derrabus Oct 21, 2022

derrabus Oct 21, 2022

derrabus Oct 21, 2022

	* This is a doctrine field, so make sure that you use an @[Column] attribute or setup your
	* This is a doctrine field, so make sure that you use an #[Column] attribute or setup your

	public function prePersistHandler(User $user, LifecycleEventArgs $event) { // ... }
	public function prePersistHandler(User $user, LifecycleEventArgs $event): void { // ... }

Migrate more documentation towards attributes #10157

Migrate more documentation towards attributes #10157

Conversation

greg0ire commented Oct 19, 2022

greg0ire commented Oct 19, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment