@note annotation causes error from Doctrine

[jtheuerkauf]

Among the changes in this commit are some annotations in the PhpDoc comments. The @note annotation is throwing errors during configure:

With:

/**
 * Create many entities with persisting them to the database.
 *
 * @param bool|null $cleanHeap Clean the heap after creating entities.
 *
 * @note To change the default value use {@see static::$cleanHeap} property.
 */

produces:

[Spiral\Attributes\Exception\SemanticAttributeException]
[Semantical Error] The annotation "@note" in method Spiral\DatabaseSeeder\Factory\AbstractFactory::create() was never imported. Did you maybe forget to add a "use" statement for this annotation?
in vendor/spiral/attributes/src/Internal/DoctrineAnnotationReader.php:87

Previous: [Doctrine\Common\Annotations\AnnotationException]
[Semantical Error] The annotation "@note" in method Spiral\DatabaseSeeder\Factory\AbstractFactory::create() was never imported. Did you maybe forget to add a "use" statement for this annotation?
in vendor/doctrine/annotations/lib/Doctrine/Common/Annotations/AnnotationException.php:36

Removing @note:

/**
 * Create many entities with persisting them to the database.
 *
 * @param bool|null $cleanHeap Clean the heap after creating entities.
 *
 * To change the default value use {@see static::$cleanHeap} property.
 */

stops the error from occurring.

---

i presume the same will be true of the createOne() method.

i'm happy to submit a change for these, if someone wants to offer an alternate annotation, or make the call to just remove @note from the remark...

Suggestions?

[jtheuerkauf]

(FWIW, my opinion is remove the annotation and combine the description with the method description:

/**
 * Create many entities with persisting them to the database.
 * To change the default value use {@see static::$cleanHeap} property.
 *
 * @param bool|null $cleanHeap Clean the heap after creating entities.
 */

It's not a valid annotation anyway, as far as i can tell.

[butschster]

Exceptions stemming from Doctrine annotations are a common issue. The optimal solution involves configuring Doctrine to ignore specific annotations.

This can be achieved with the following line of code:

\Doctrine\Common\Annotations\AnnotationReader::addGlobalIgnoredName('note');

This code snippet should be inserted into a bootloader to guarantee its execution at an early stage in the application's lifecycle. Ensure that this bootloader is positioned at the beginning of the system's bootloader section for optimal effectiveness.

[jtheuerkauf]

Good to know, thanks for that!

Obviously, comments shouldn't have to be scrutinized for functional impact, but here we are.

It seems to me that if the code involved (AbstractFactory) must be parsed by Doctrine, then complying with supported PHPDoc syntax/tags is preferable to adding the functional overhead of a workaround.

(Especially in this case where there seems to be no functional/documentation advantage to an invalid @note tag)