[Console][EventDispatcher][Security][Serializer][Workflow] Add PHPDoc to attribute classes and properties

alexandre-daubois · alexandre-daubois · commit 0c2852519b89 · 2023-10-15T11:14:27.000+02:00
diff --git a/src/Symfony/Component/Console/Attribute/AsCommand.php b/src/Symfony/Component/Console/Attribute/AsCommand.php
@@ -17,8 +17,19 @@
 #[\Attribute(\Attribute::TARGET_CLASS)]
 class AsCommand
 {
+    /**
+     * @param string[] $aliases The list of aliases of the command. The command will be executed when using one of them (i.e. "cache:clean")
+     * @param bool     $hidden  If true, the command won't be shown when listing all the available commands, but it can still be run as any other command
+     */
     public function __construct(
+        /**
+         * The name of the command, used when calling it (i.e. "cache:clear").
+         */
         public string $name,
+
+        /**
+         * The description of the command, displayed with the help page.
+         */
         public ?string $description = null,
         array $aliases = [],
         bool $hidden = false,
diff --git a/src/Symfony/Component/EventDispatcher/Attribute/AsEventListener.php b/src/Symfony/Component/EventDispatcher/Attribute/AsEventListener.php
@@ -20,9 +20,26 @@
 class AsEventListener
 {
     public function __construct(
+        /**
+         * The event name to listen to.
+         */
         public ?string $event = null,
+
+        /**
+         * The method to run when the listened event is triggered.
+         */
         public ?string $method = null,
+
+        /**
+         * The priority of this listener if several are declared for the same event.
+         * Listeners with the highest priority are called first.
+         * Use the "debug:event-dispatcher" command to show priorities of other listeners.
+         */
         public int $priority = 0,
+
+        /**
+         * The service id of the event dispatcher to listen to.
+         */
         public ?string $dispatcher = null,
     ) {
     }
diff --git a/src/Symfony/Component/Security/Core/Validator/Constraints/UserPassword.php b/src/Symfony/Component/Security/Core/Validator/Constraints/UserPassword.php
@@ -15,6 +15,7 @@
 
 /**
  * @Annotation
+ *
  * @Target({"PROPERTY", "METHOD", "ANNOTATION"})
  */
 #[\Attribute(\Attribute::TARGET_PROPERTY | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
@@ -29,6 +30,13 @@ class UserPassword extends Constraint
     public $message = 'This value should be the user\'s current password.';
     public $service = 'security.validator.user_password';
 
+    /**
+     * @param array<array-key, mixed>|null  $options Options passed to the validation constraint
+     * @param string|null $message The message to display if this constraint raises a violation
+     * @param string|null $service The service id to use to check the user current password
+     * @param string[]|null  $groups  The groups on which this validation constraint applies (@see https://symfony.com/doc/current/validation/groups.html)
+     * @param mixed  $payload Arbitrary data passed to the constraint to make any additional checks in the constraint validator
+     */
     public function __construct(array $options = null, string $message = null, string $service = null, array $groups = null, mixed $payload = null)
     {
         parent::__construct($options, $groups, $payload);
diff --git a/src/Symfony/Component/Security/Http/Attribute/CurrentUser.php b/src/Symfony/Component/Security/Http/Attribute/CurrentUser.php
@@ -20,6 +20,10 @@
 #[\Attribute(\Attribute::TARGET_PARAMETER)]
 class CurrentUser extends ValueResolver
 {
+    /**
+     * @param bool   $disabled Whether this value resolver is disabled, which allows to enable a value resolver globally while disabling it in specific cases
+     * @param string $resolver The class name of the resolver to use
+     */
     public function __construct(bool $disabled = false, string $resolver = UserValueResolver::class)
     {
         parent::__construct($resolver, $disabled);
diff --git a/src/Symfony/Component/Security/Http/Attribute/IsGranted.php b/src/Symfony/Component/Security/Http/Attribute/IsGranted.php
@@ -14,6 +14,10 @@
 use Symfony\Component\ExpressionLanguage\Expression;
 
 /**
+ * Checks if user has permission to access to some resource using security roles.
+ *
+ * @see https://symfony.com/doc/current/security.html#roles
+ *
  * @author Ryan Weaver <ryan@knpuniversity.com>
  */
 #[\Attribute(\Attribute::IS_REPEATABLE | \Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::TARGET_FUNCTION)]
diff --git a/src/Symfony/Component/Serializer/Annotation/Context.php b/src/Symfony/Component/Serializer/Annotation/Context.php
@@ -16,8 +16,12 @@
 /**
  * Annotation class for @Context().
  *
+ * An attribute to define a context during normalization and denormalization processes.
+ *
  * @Annotation
+ *
  * @NamedArgumentConstructor
+ *
  * @Target({"PROPERTY", "METHOD"})
  *
  * @author Maxime Steinhausser <maxime.steinhausser@gmail.com>
@@ -28,13 +32,24 @@ class Context
     private array $groups;
 
     /**
-     * @param string|string[] $groups
+     * @param string|string[] $groups The groups on which to apply the defined context
      *
      * @throws InvalidArgumentException
      */
     public function __construct(
+        /**
+         * The context being used during any operation.
+         */
         private readonly array $context = [],
+
+        /**
+         * The context being used during the normalization process.
+         */
         private readonly array $normalizationContext = [],
+
+        /**
+         * The context being used during the denormalization process.
+         */
         private readonly array $denormalizationContext = [],
         string|array $groups = [],
     ) {
diff --git a/src/Symfony/Component/Serializer/Annotation/DiscriminatorMap.php b/src/Symfony/Component/Serializer/Annotation/DiscriminatorMap.php
@@ -16,8 +16,13 @@
 /**
  * Annotation class for @DiscriminatorMap().
  *
+ * An attribute to define a matching between a type discriminator and a class when dealing with
+ * abstract classes and interfaces.
+ *
  * @Annotation
+ *
  * @NamedArgumentConstructor
+ *
  * @Target({"CLASS"})
  *
  * @author Samuel Roze <samuel.roze@gmail.com>
@@ -26,7 +31,16 @@
 class DiscriminatorMap
 {
     public function __construct(
+        /**
+         * The property holding the type discriminator.
+         */
         private readonly string $typeProperty,
+
+        /**
+         * The mapping between types and classes (i.e. ['admin_user' => AdminUser::class]).
+         *
+         * @var array<string, class-string>
+         */
         private readonly array $mapping,
     ) {
         if (empty($typeProperty)) {
diff --git a/src/Symfony/Component/Serializer/Annotation/Groups.php b/src/Symfony/Component/Serializer/Annotation/Groups.php
@@ -16,8 +16,12 @@
 /**
  * Annotation class for @Groups().
  *
+ * An attribute to define serialization groups on a method, a property or a class.
+ *
  * @Annotation
+ *
  * @NamedArgumentConstructor
+ *
  * @Target({"PROPERTY", "METHOD", "CLASS"})
  *
  * @author Kévin Dunglas <dunglas@gmail.com>
@@ -31,7 +35,7 @@ class Groups
     private readonly array $groups;
 
     /**
-     * @param string|string[] $groups
+     * @param string|string[] $groups The groups to define on the attribute target
      */
     public function __construct(string|array $groups)
     {
diff --git a/src/Symfony/Component/Serializer/Annotation/Ignore.php b/src/Symfony/Component/Serializer/Annotation/Ignore.php
@@ -14,7 +14,10 @@
 /**
  * Annotation class for @Ignore().
  *
+ * An attribute to declare a property or a method to ignore during the serialization process.
+ *
  * @Annotation
+ *
  * @Target({"PROPERTY", "METHOD"})
  *
  * @author Kévin Dunglas <dunglas@gmail.com>
diff --git a/src/Symfony/Component/Serializer/Annotation/MaxDepth.php b/src/Symfony/Component/Serializer/Annotation/MaxDepth.php
@@ -16,17 +16,25 @@
 /**
  * Annotation class for @MaxDepth().
  *
+ * An attribute to define the maximum serialization depth of the target.
+ *
  * @Annotation
+ *
  * @NamedArgumentConstructor
+ *
  * @Target({"PROPERTY", "METHOD"})
  *
  * @author Kévin Dunglas <dunglas@gmail.com>
  */
 #[\Attribute(\Attribute::TARGET_METHOD | \Attribute::TARGET_PROPERTY)]
 class MaxDepth
 {
-    public function __construct(private readonly int $maxDepth)
-    {
+    public function __construct(
+        /**
+         * The maximum serialization depth.
+         */
+        private readonly int $maxDepth
+    ) {
         if ($maxDepth <= 0) {
             throw new InvalidArgumentException(sprintf('Parameter of annotation "%s" must be a positive integer.', static::class));
         }
diff --git a/src/Symfony/Component/Serializer/Annotation/SerializedName.php b/src/Symfony/Component/Serializer/Annotation/SerializedName.php
@@ -16,17 +16,25 @@
 /**
  * Annotation class for @SerializedName().
  *
+ * An attribute to define the name of the target once serialized.
+ *
  * @Annotation
+ *
  * @NamedArgumentConstructor
+ *
  * @Target({"PROPERTY", "METHOD"})
  *
  * @author Fabien Bourigault <bourigaultfabien@gmail.com>
  */
 #[\Attribute(\Attribute::TARGET_METHOD | \Attribute::TARGET_PROPERTY)]
 final class SerializedName
 {
-    public function __construct(private readonly string $serializedName)
-    {
+    public function __construct(
+        /**
+         * The name to use in the result of the serialization process.
+         */
+        private readonly string $serializedName
+    ) {
         if ('' === $serializedName) {
             throw new InvalidArgumentException(sprintf('Parameter of annotation "%s" must be a non-empty string.', self::class));
         }
diff --git a/src/Symfony/Component/Serializer/Annotation/SerializedPath.php b/src/Symfony/Component/Serializer/Annotation/SerializedPath.php
@@ -18,8 +18,12 @@
 /**
  * Annotation class for @SerializedPath().
  *
+ * An attribute to define the path of a value during the denormalization process.
+ *
  * @Annotation
+ *
  * @NamedArgumentConstructor
+ *
  * @Target({"PROPERTY", "METHOD"})
  *
  * @author Tobias Bönner <tobi@boenner.family>
@@ -29,6 +33,9 @@ final class SerializedPath
 {
     private PropertyPath $serializedPath;
 
+    /**
+     * @param string $serializedPath A path using a valid PropertyAccess syntax where the value is stored in a normalized representation
+     */
     public function __construct(string $serializedPath)
     {
         try {
diff --git a/src/Symfony/Component/Workflow/Attribute/AsAnnounceListener.php b/src/Symfony/Component/Workflow/Attribute/AsAnnounceListener.php
@@ -14,13 +14,22 @@
 use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
 
 /**
+ * An attribute to define a listener for the "announce" event of a workflow.
+ *
  * @author Grégoire Pineau <lyrixx@lyrixx.info>
  */
 #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
 final class AsAnnounceListener extends AsEventListener
 {
     use BuildEventNameTrait;
 
+    /**
+     * @param string|null $workflow   The id of the workflow to listen to
+     * @param string|null $transition The transition name to which the listener listens to
+     * @param string|null $method     The method to run when the listened event is triggered
+     * @param int         $priority   The priority of this listener if several are declared for the same transition
+     * @param string|null $dispatcher The service id of the event dispatcher to listen to
+     */
     public function __construct(
         string $workflow = null,
         string $transition = null,
diff --git a/src/Symfony/Component/Workflow/Attribute/AsCompletedListener.php b/src/Symfony/Component/Workflow/Attribute/AsCompletedListener.php
@@ -21,6 +21,13 @@ final class AsCompletedListener extends AsEventListener
 {
     use BuildEventNameTrait;
 
+    /**
+     * @param string|null $workflow   The id of the workflow to listen to
+     * @param string|null $transition The transition name to which the listener listens to
+     * @param string|null $method     The method to run when the listened event is triggered
+     * @param int         $priority   The priority of this listener if several are declared for the same transition
+     * @param string|null $dispatcher The service id of the event dispatcher to listen to
+     */
     public function __construct(
         string $workflow = null,
         string $transition = null,
diff --git a/src/Symfony/Component/Workflow/Attribute/AsEnterListener.php b/src/Symfony/Component/Workflow/Attribute/AsEnterListener.php
@@ -21,6 +21,13 @@ final class AsEnterListener extends AsEventListener
 {
     use BuildEventNameTrait;
 
+    /**
+     * @param string|null $workflow   The id of the workflow to listen to
+     * @param string|null $place      The place name to which the listener listens to
+     * @param string|null $method     The method to run when the listened event is triggered
+     * @param int         $priority   The priority of this listener if several are declared for the same place
+     * @param string|null $dispatcher The service id of the event dispatcher to listen to
+     */
     public function __construct(
         string $workflow = null,
         string $place = null,
diff --git a/src/Symfony/Component/Workflow/Attribute/AsEnteredListener.php b/src/Symfony/Component/Workflow/Attribute/AsEnteredListener.php
@@ -21,6 +21,13 @@ final class AsEnteredListener extends AsEventListener
 {
     use BuildEventNameTrait;
 
+    /**
+     * @param string|null $workflow   The id of the workflow to listen to
+     * @param string|null $place      The place name to which the listener listens to
+     * @param string|null $method     The method to run when the listened event is triggered
+     * @param int         $priority   The priority of this listener if several are declared for the same place
+     * @param string|null $dispatcher The service id of the event dispatcher to listen to
+     */
     public function __construct(
         string $workflow = null,
         string $place = null,
diff --git a/src/Symfony/Component/Workflow/Attribute/AsGuardListener.php b/src/Symfony/Component/Workflow/Attribute/AsGuardListener.php
@@ -21,6 +21,13 @@ final class AsGuardListener extends AsEventListener
 {
     use BuildEventNameTrait;
 
+    /**
+     * @param string|null $workflow   The id of the workflow to listen to
+     * @param string|null $transition The transition name to which the listener listens to
+     * @param string|null $method     The method to run when the listened event is triggered
+     * @param int         $priority   The priority of this listener if several are declared for the same transition
+     * @param string|null $dispatcher The service id of the event dispatcher to listen to
+     */
     public function __construct(
         string $workflow = null,
         string $transition = null,
diff --git a/src/Symfony/Component/Workflow/Attribute/AsLeaveListener.php b/src/Symfony/Component/Workflow/Attribute/AsLeaveListener.php
@@ -21,6 +21,13 @@ final class AsLeaveListener extends AsEventListener
 {
     use BuildEventNameTrait;
 
+    /**
+     * @param string|null $workflow   The id of the workflow to listen to
+     * @param string|null $place      The place name to which the listener listens to
+     * @param string|null $method     The method to run when the listened event is triggered
+     * @param int         $priority   The priority of this listener if several are declared for the same place
+     * @param string|null $dispatcher The service id of the event dispatcher to listen to
+     */
     public function __construct(
         string $workflow = null,
         string $place = null,
diff --git a/src/Symfony/Component/Workflow/Attribute/AsTransitionListener.php b/src/Symfony/Component/Workflow/Attribute/AsTransitionListener.php
@@ -21,6 +21,13 @@ final class AsTransitionListener extends AsEventListener
 {
     use BuildEventNameTrait;
 
+    /**
+     * @param string|null $workflow   The id of the workflow to listen to
+     * @param string|null $transition The transition name to which the listener listens to
+     * @param string|null $method     The method to run when the listened event is triggered
+     * @param int         $priority   The priority of this listener if several are declared for the same transition
+     * @param string|null $dispatcher The service id of the event dispatcher to listen to
+     */
     public function __construct(
         string $workflow = null,
         string $transition = null,

Original file line number	Diff line number	Diff line change
`@@ -20,6 +20,10 @@`
`20`	`20`	`#[\Attribute(\Attribute::TARGET_PARAMETER)]`
`21`	`21`	`class CurrentUser extends ValueResolver`
`22`	`22`	`{`
	`23`	`+ /**`
	`24`	`+ * @param bool $disabled Whether this value resolver is disabled, which allows to enable a value resolver globally while disabling it in specific cases`
	`25`	`+ * @param string $resolver The class name of the resolver to use`
	`26`	`+ */`
`23`	`27`	`public function __construct(bool $disabled = false, string $resolver = UserValueResolver::class)`
`24`	`28`	`{`
`25`	`29`	`parent::__construct($resolver, $disabled);`
Original file line number	Diff line number	Diff line change
`@@ -14,7 +14,10 @@`
`14`	`14`	`/**`
`15`	`15`	`* Annotation class for @Ignore().`
`16`	`16`	`*`
	`17`	`+ * An attribute to declare a property or a method to ignore during the serialization process.`
	`18`	`+ *`
`17`	`19`	`* @Annotation`
	`20`	`+ *`
`18`	`21`	`* @Target({"PROPERTY", "METHOD"})`
`19`	`22`	`*`
`20`	`23`	`* @author Kévin Dunglas <dunglas@gmail.com>`