Description and example inside array response?

[Shadercloud]

Is there a way to add examples and descriptions inside of an array type response? For example:

return [
    'success' => true,
    /* @var array<array{
     *     name: string,
     *     id: int,
     *     abilities: array,
     *     created_at: string,
     *     last_used_at: string
     * }> List of Tokens
     */
    'tokens'  => $user->tokens->map(function ($token) {
        return [
            'name'         => $token->name,
            'id'           => $token->id,
            'abilities'    => $token->abilities,
            'created_at'   => $token->created_at,
            'last_used_at' => $token->last_used_at,
        ];
    })
];

Currently it seems this is the limitation of what you can do inside an array (basically just return a type only for each field)

I'd like to be able to add example field for each of the nest array fields (such as an example for "name")

[romalytvynenko]

@Shadercloud not possible now to do that in the PHPDoc 🫠

Any ideas for how it could be done?

[Shadercloud]

I would suggest a format such as this:

* @var array<array{
     *     name: var{type: string, description: 'Something goes here', example: 'Here is an example'},
     *     id: int,
     *     abilities: array,
     *     created_at: string,
     *     last_used_at: string
     * }>
     */

So that the value from the key=>value of the array can be evalulated in detail.

[Shadercloud]

Note that this also seems linked with this issue: #666

So one could solve it by allowing the above detailed array PHPDoc notes; or by allowing PHPDoc notes inside the map (this approach seems like it would take a lot more work though). But i guess the perfect solution would be to automatically detect variables inside map.