minor symfony#51974 [Console][EventDispatcher][Security][Serializer][Workflow] Add PHPDoc to attribute classes and properties (alexandre-daubois)

This PR was merged into the 7.1 branch.

Discussion
----------

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

| Q             | A
| ------------- | ---
| Branch?       | 7.1
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Tickets       | Part of symfony#51920
| License       | MIT

One more round.

:information_source: A first review of this kind is being done [here](symfony#51971), I'll adjust this PR accordingly once done 🙂

Commits
-------

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

Author: nicolas-grekas

src/Symfony/Component/Console/Attribute/AsCommand.php

@@ -17,6 +17,12 @@
 #[\Attribute(\Attribute::TARGET_CLASS)]
 class AsCommand
 {
+    /**
+     * @param string      $name        The name of the command, used when calling it (i.e. "cache:clear")
+     * @param string|null $description The description of the command, displayed with the help page
+     * @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(
         public string $name,
         public ?string $description = null,

src/Symfony/Component/EventDispatcher/Attribute/AsEventListener.php

@@ -19,6 +19,12 @@
 #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
 class AsEventListener
 {
+    /**
+     * @param string|null $event      The event name to listen 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 event
+     * @param string|null $dispatcher The service id of the event dispatcher to listen to
+     */
     public function __construct(
         public ?string $event = null,
         public ?string $method = null,

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);

src/Symfony/Component/Security/Http/Attribute/IsGranted.php

@@ -14,38 +14,27 @@
 use Symfony\Component\ExpressionLanguage\Expression;
 
 /**
+ * Checks if user has permission to access to some resource using security roles and voters.
+ *
+ * @see https://symfony.com/doc/current/security.html#roles
+ *
  * @author Ryan Weaver <[email protected]>
  */
 #[\Attribute(\Attribute::IS_REPEATABLE | \Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::TARGET_FUNCTION)]
 final class IsGranted
 {
+    /**
+     * @param string|Expression            $attribute     The attribute that will be checked against a given authentication token and optional subject
+     * @param array|string|Expression|null $subject       An optional subject - e.g. the current object being voted on
+     * @param string|null                  $message       A custom message when access is not granted
+     * @param int|null                     $statusCode    If set, will throw HttpKernel's HttpException with the given $statusCode; if null, Security\Core's AccessDeniedException will be used
+     * @param int|null                     $exceptionCode If set, will add the exception code to thrown exception
+     */
     public function __construct(
-        /**
-         * Sets the first argument that will be passed to isGranted().
-         */
         public string|Expression $attribute,
-
-        /**
-         * Sets the second argument passed to isGranted().
-         *
-         * @var array<string|Expression>|string|Expression|null
-         */
         public array|string|Expression|null $subject = null,
-
-        /**
-         * The message of the exception - has a nice default if not set.
-         */
         public ?string $message = null,
-
-        /**
-         * If set, will throw HttpKernel's HttpException with the given $statusCode.
-         * If null, Security\Core's AccessDeniedException will be used.
-         */
         public ?int $statusCode = null,
-
-        /**
-         * If set, will add the exception code to thrown exception.
-         */
         public ?int $exceptionCode = null,
     ) {
     }

src/Symfony/Component/Serializer/Attribute/Context.php

@@ -22,7 +22,10 @@ class Context
     private array $groups;
 
     /**
-     * @param string|string[] $groups
+     * @param array<string, mixed> $context                The common context to use when serializing or deserializing
+     * @param array<string, mixed> $normalizationContext   The context to use when serializing
+     * @param array<string, mixed> $denormalizationContext The context to use when deserializing
+     * @param string|string[]      $groups                 The groups to use when serializing or deserializing
      *
      * @throws InvalidArgumentException
      */

src/Symfony/Component/Serializer/Attribute/DiscriminatorMap.php

@@ -19,6 +19,12 @@
 #[\Attribute(\Attribute::TARGET_CLASS)]
 class DiscriminatorMap
 {
+    /**
+     * @param string                      $typeProperty The property holding the type discriminator
+     * @param array<string, class-string> $mapping      The mapping between types and classes (i.e. ['admin_user' => AdminUser::class])
+     *
+     * @throws InvalidArgumentException
+     */
     public function __construct(
         private readonly string $typeProperty,
         private readonly array $mapping,

src/Symfony/Component/Serializer/Attribute/Groups.php

@@ -25,7 +25,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)
     {

src/Symfony/Component/Serializer/Attribute/MaxDepth.php

@@ -19,6 +19,9 @@
 #[\Attribute(\Attribute::TARGET_METHOD | \Attribute::TARGET_PROPERTY)]
 class MaxDepth
 {
+    /**
+     * @param int $maxDepth The maximum serialization depth
+     */
     public function __construct(private readonly int $maxDepth)
     {
         if ($maxDepth <= 0) {

src/Symfony/Component/Serializer/Attribute/SerializedName.php

@@ -19,6 +19,9 @@
 #[\Attribute(\Attribute::TARGET_METHOD | \Attribute::TARGET_PROPERTY)]
 class SerializedName
 {
+    /**
+     * @param string $serializedName The name of the property as it will be serialized
+     */
     public function __construct(private readonly string $serializedName)
     {
         if ('' === $serializedName) {

src/Symfony/Component/Serializer/Attribute/SerializedPath.php

@@ -23,6 +23,9 @@ 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 {