Modernize documentation code #10126

greg0ire · 2022-10-12T19:20:26Z

migrate to attributes;
add helpful phpdoc annotations;
use typed properties;
add type declarations.

docs/en/reference/working-with-associations.rst

greg0ire · 2022-10-12T19:30:57Z

🤔 should I be targeting 2.13.x? After all, there is not much reason to wait for this.

derrabus · 2022-10-12T19:53:01Z

docs/en/reference/working-with-associations.rst

-        private $firstComment;
+        /** Unidirectional - Many-To-One */
+        #[ManyToOne(targetEntity: Comment::class)]
+        private Comment $firstComment;


Suggested change

private Comment $firstComment;

private Comment|null $firstComment = null;

ManyToOne relations are nullable by default.

docs/en/reference/working-with-associations.rst

derrabus · 2022-10-12T19:56:36Z

🤔 should I be targeting 2.13.x? After all, there is not much reason to wait for this.

I wouldn't wait with the 2.14.0 release too long either, so targeting 2.14.x is just fine imho.

docs/en/reference/working-with-associations.rst

greg0ire · 2022-10-15T10:03:06Z

I wouldn't wait with the 2.14.0 release too long either, so targeting 2.14.x is just fine imho.

I retargeted to 2.13.x so as not to have things to convert when merging up.

docs/en/cookbook/working-with-datetime.rst

docs/en/reference/association-mapping.rst

docs/en/reference/dql-doctrine-query-language.rst

docs/en/reference/inheritance-mapping.rst

docs/en/reference/transactions-and-concurrency.rst

docs/en/reference/working-with-associations.rst

docs/en/reference/working-with-objects.rst

docs/en/tutorials/composite-primary-keys.rst

greg0ire · 2022-10-17T19:37:35Z

@derrabus please take another look 🙏

docs/en/cookbook/decorator-pattern.rst

docs/en/tutorials/composite-primary-keys.rst

docs/en/tutorials/ordered-associations.rst

- migrate to attributes; - add helpful phpdoc annotations; - use typed properties; - add type declarations. Co-authored-by: Alexander M. Turek <me@derrabus.de>

greg0ire · 2022-10-17T20:58:05Z

Shall we propagate CPP here?

I applied your suggestions and removed the property that was outside the constructor for that particular comment.

SenseException

PHP 7.4 is nearly gone, but it still feels weird to have attributes as the primary configuration when PHP 7 is still supported in composer :-D

stof · 2022-10-18T08:32:06Z

docs/en/reference/basic-mapping.rst

@@ -451,17 +449,15 @@ besides specifying the sequence's name:

 .. configuration-block::

-    .. code-block:: php
+    .. code-block:: attribute


As we have several formats here, shouldn't we keep the annotation code-block too ?

It would be better yeah, I'll try to find some time to do that.

oleg-andreyev · 2022-10-19T05:03:13Z

docs/en/cookbook/decorator-pattern.rst

-     * @DiscriminatorMap({"cc" = "Test\Component\ConcreteComponent",
-        "cd" = "Test\Decorator\ConcreteDecorator"})
-     */
+    #[Entity]


Despite the fact that branch is already merged: I personally prefer multiple attributes in single '#[...]' looks a bit cleaner ;)

It was like that before 🤷

oleg-andreyev · 2022-10-19T05:06:51Z

docs/en/reference/change-tracking-policies.rst

-
-        public function addPropertyChangedListener(PropertyChangedListener $listener)
+
+        private array $_listeners = array();


Short array?

Please consider sending a PR

oleg-andreyev · 2022-10-19T05:07:55Z

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;


If referring to 8.1, enum example can be used here :)

oleg-andreyev · 2022-10-19T05:10:41Z

docs/en/reference/inheritance-mapping.rst

+        #[Id, Column(type: 'integer')]
+        private int|null $id = null;
+        #[Column(type: 'string')]
+        private string $name;


Probably should provide a default value, otherwise: creating new entity and calling getName will return fatal - if getter is strict too.

On the other hand, you might have a constructor preventing this entirely.

oleg-andreyev · 2022-10-19T05:13:54Z

docs/en/reference/second-level-cache.rst

-         * @Cache("NONSTRICT_READ_WRITE")
-         */
+        #[Entity]
+        #[Cache(usage: 'NONSTRICT_READ_WRITE')]


This string can be a real constant

What do you mean?

oleg-andreyev · 2022-10-19T05:14:57Z

docs/en/reference/working-with-associations.rst

             return $this->commentsRead;
        }

-        public function setFirstComment(Comment $c) {
+        /** @param Collection<int, Comment> $c */


Wrong comment?

Good catch 👍

oleg-andreyev · 2022-10-19T05:16:36Z

docs/en/reference/working-with-associations.rst

-        private $comments;
+        private int $id;
+
+        /** @var Collection<int, Comment> */


Here: key can be mixed as we don't know how people are adding to collection via add or set :)

And if they do, they should get a warning from PHPStan/Psalm thanks to this annotation, so I stand by it.

greg0ire · 2022-10-19T06:57:23Z

To anyone finding more stuff to say after the merge: please send PRs instead 🙏

michnovka · 2022-10-19T10:35:24Z

docs/en/cookbook/decorator-pattern.rst

+    #[DiscriminatorMap(['cc' => Component\ConcreteComponent::class,
+        'cd' => Decorator\ConcreteDecorator::class])]


See discussion here slevomat/coding-standard#1456

greg0ire added the Documentation label Oct 12, 2022

greg0ire commented Oct 12, 2022

View reviewed changes

docs/en/reference/working-with-associations.rst Show resolved Hide resolved

greg0ire commented Oct 12, 2022

View reviewed changes

docs/en/reference/working-with-associations.rst Outdated Show resolved Hide resolved

greg0ire commented Oct 12, 2022

View reviewed changes

docs/en/reference/working-with-associations.rst Outdated Show resolved Hide resolved

greg0ire commented Oct 12, 2022

View reviewed changes

docs/en/reference/working-with-associations.rst Show resolved Hide resolved

derrabus reviewed Oct 12, 2022

View reviewed changes

docs/en/reference/working-with-associations.rst Outdated Show resolved Hide resolved

greg0ire force-pushed the migrate-docs-to-attributes branch from e4664b8 to e762952 Compare October 15, 2022 08:09

derrabus reviewed Oct 15, 2022

View reviewed changes

docs/en/reference/working-with-associations.rst Outdated Show resolved Hide resolved

greg0ire force-pushed the migrate-docs-to-attributes branch from e762952 to 7cbdc4a Compare October 15, 2022 09:55

greg0ire changed the base branch from 2.14.x to 2.13.x October 15, 2022 09:55

greg0ire force-pushed the migrate-docs-to-attributes branch from 7cbdc4a to 2ecfee9 Compare October 15, 2022 09:55

greg0ire force-pushed the migrate-docs-to-attributes branch from 2ecfee9 to 7486f2a Compare October 15, 2022 10:29

greg0ire mentioned this pull request Oct 15, 2022

Run only relevant workflows #10134

Merged

greg0ire force-pushed the migrate-docs-to-attributes branch 4 times, most recently from 8535f95 to 45d53e4 Compare October 15, 2022 14:03

greg0ire marked this pull request as ready for review October 15, 2022 14:10

greg0ire changed the title ~~Migrate documentation to attributes~~ Modernize documentation code Oct 15, 2022

greg0ire requested review from derrabus and SenseException October 15, 2022 14:11

derrabus requested changes Oct 15, 2022

View reviewed changes

greg0ire force-pushed the migrate-docs-to-attributes branch 4 times, most recently from b964d68 to c1eef4a Compare October 15, 2022 17:29

greg0ire force-pushed the migrate-docs-to-attributes branch from c1eef4a to 4eb9289 Compare October 15, 2022 17:32

greg0ire requested a review from derrabus October 15, 2022 17:33

derrabus requested changes Oct 17, 2022

View reviewed changes

Modernize documentation code

794777b

- migrate to attributes; - add helpful phpdoc annotations; - use typed properties; - add type declarations. Co-authored-by: Alexander M. Turek <me@derrabus.de>

greg0ire force-pushed the migrate-docs-to-attributes branch from 66cba2c to 794777b Compare October 17, 2022 20:56

greg0ire requested a review from derrabus October 17, 2022 20:57

derrabus approved these changes Oct 17, 2022

View reviewed changes

greg0ire added this to the 2.13.4 milestone Oct 17, 2022

greg0ire merged commit 5f4b76b into doctrine:2.13.x Oct 17, 2022

greg0ire deleted the migrate-docs-to-attributes branch October 17, 2022 21:11

SenseException approved these changes Oct 17, 2022

View reviewed changes

stof reviewed Oct 18, 2022

View reviewed changes

oleg-andreyev reviewed Oct 19, 2022

View reviewed changes

michnovka reviewed Oct 19, 2022

View reviewed changes

greg0ire mentioned this pull request Oct 19, 2022

Migrate more documentation towards attributes #10157

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Modernize documentation code #10126

Modernize documentation code #10126

greg0ire commented Oct 12, 2022 •

edited

Loading

greg0ire commented Oct 12, 2022

derrabus Oct 12, 2022

derrabus commented Oct 12, 2022

greg0ire commented Oct 15, 2022

greg0ire commented Oct 17, 2022

greg0ire commented Oct 17, 2022

SenseException left a comment

stof Oct 18, 2022

greg0ire Oct 19, 2022

greg0ire Oct 19, 2022

oleg-andreyev Oct 19, 2022

greg0ire Oct 19, 2022

oleg-andreyev Oct 19, 2022

greg0ire Oct 19, 2022

oleg-andreyev Oct 19, 2022

oleg-andreyev Oct 19, 2022

greg0ire Oct 19, 2022

oleg-andreyev Oct 19, 2022

greg0ire Oct 19, 2022

oleg-andreyev Oct 19, 2022

greg0ire Oct 19, 2022

oleg-andreyev Oct 19, 2022

greg0ire Oct 19, 2022

greg0ire commented Oct 19, 2022

michnovka Oct 19, 2022

	private Comment $firstComment;
	private Comment\|null $firstComment = null;


		public function addPropertyChangedListener(PropertyChangedListener $listener)

		private array $_listeners = array();

		#[DiscriminatorMap(['cc' => Component\ConcreteComponent::class,
		'cd' => Decorator\ConcreteDecorator::class])]

Modernize documentation code #10126

Modernize documentation code #10126

Conversation

greg0ire commented Oct 12, 2022 • edited Loading

greg0ire commented Oct 12, 2022

Choose a reason for hiding this comment

derrabus commented Oct 12, 2022

greg0ire commented Oct 15, 2022

greg0ire commented Oct 17, 2022

greg0ire commented Oct 17, 2022

SenseException left a 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

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

greg0ire commented Oct 19, 2022

Choose a reason for hiding this comment

greg0ire commented Oct 12, 2022 •

edited

Loading