Support multiline description

[dmitrach]

I've have a long description, there is more 120 characters in a line and it is a problem for reading and for PHP CS Fixer.

I would like to divide the line into multiple lines. Currently I cannot do it due to extra symbols like * of a multiline comment. Also it cannot work with markdown, for example, a list.

/*
 * @OA\Schema(
 *   schema="AuthorizationStatus",
 *   type="integer",
 *   description=">
 *     An authorization status: 
 *     - 1 - registration isn't finished, 
 *     - 2 - a user has an active booking, 
 *     - 3 - a user has been registered without an active booking.",
 *   enum={1, 2, 3},
 *   example=1
 * )
 */

The current result.

description: ">\n *   An authorization status:\n *   - 1 - registration isn't finished,\n *   - 2 - a user has an active booking, \n *   3 - a user has been registered without an active booking."

Expected.

description: >
  An authorization status:
  - 1 - registration isn't finished,
  - 2 - a user has an active booking, 
  - 3 - a user has been registered without an active booking.

As a result I've removed * from comments to get the desired result.

/*
 * @OA\Schema(
 *   schema="AuthorizationStatus",
 *   type="integer",
 *   description=">
An authorization status: 
- 1 - registration isn't finished, 
- 2 - a user has an active booking, 
- 3 - a user has been registered without an active booking.",
 *   enum={1, 2, 3},
 *   example=1
 * )
 */

[DerManoMann]

Might be something to just document. Looking at the Doctrine Annotations project I do not think that is going to be supported at all.

[rlehner-dk]

I recommend the usage of PHP 8.2 attributes, with HEREDOC
Unfortunately I did not find this way in the documentary either

#[OA\Schema(
    schema: 'AuthorizationStatus',
    description: <<<HEREDOC
    An authorization status: 
    - 1 - registration isn't finished, 
    - 2 - a user has an active booking, 
    - 3 - a user has been registered without an active booking.
    HEREDOC,
    type: 'integer',
    enum: [1, 2, 3],
    example: 1
)]