PHP variadic function wrong variable name

[jfcherng]

Problem

Variadic function is introduced in PHP 5.6. Here's a simple example.

function variadicFunction(...$args): array
{
    return $args;
}

The generated PHPDoc looks like the following.

/**
 * { function_description }
 *
 * @param ... $args The arguments
 *
 * @return ...|array ( description_of_the_return_value )
 */
function variadicFunction(...$args): array
{
    return $args;
}

It looks like the ... is treated as the variable type of $arg but actually it is not and no type is declared here.

Expected Result

/**
 * { function_description }
 *
 * @param <type> ...$args The arguments
 *
 * @return array ( description_of_the_return_value )
 */
function variadicFunction(...$args): array
{
    return $args;
}

Just a note. Here, the <type> is the type of the element of $args rather than $args itself.

Reference: https://github.com/phpDocumentor/fig-standards/issues/121#issuecomment-429202033

Another Problem that May Be Related

Say, now I have my doc edited manually as the following.

/**
 * This is a variadic function.
 *
 * @param mixed ...$args The arguments
 *
 * @return array
 */
function variadicFunction(...$args): array
{
    return $args;
}

Now I press Alt+Q(doxy_comment_nearest_entity). The doc becomes

/**
 * This is a variadic function.
 *
 * @param mixed $args The arguments
 *
 * @return array
 */
function variadicFunction(...$args): array
{
    return $args;
}

The ... is removed by plugin.

[20Tauri]

Thanks for reporting,

As the current generated comment match no recommendation, I have implemented your suggestion ("old" PhpStorm syntax)...

But the syntax seems tools dependant (discussed here on StackOverflow )

PhpDoc documentation defines:

/**
 * @param mixed $args,... The arguments
 */

This option seem to be a better choice... What is your opinion about this syntax ? Is it compliant with your editor ?

[jfcherng]

Yes, it's okay in my use case as well. Either way, it's better than the current one. Thanks!

[20Tauri]

Thanks

0.71.0 is now released on the evolution branch Will be pushed in the regular branch next week

[jfcherng]

Works for me. Thanks.

[jfcherng]

It looks like my static analyzer (phan) doesn't like this syntax. I have to check with the author.

[jfcherng]

I check some most famous PHP static analysis tools.

• phpstan: https://github.com/phpstan/phpstan/issues/1530#issuecomment-431654951
• phan (the one I use curretly): https://github.com/phan/phan/issues/2982#issuecomment-512082382
• psalm: https://github.com/vimeo/psalm/issues/148#issuecomment-296687779

All of them are using @param <type> ...$args as the doc of a variadic funciton. Since PHPStorm also accepts that form, I suggest we use it as the default one for best compatibility. Or, hopefully make it configurable as an user preference.

[20Tauri]

Thanks again,

0.71.1 is now released. On comment update the "...$args" notation will be applied

[jfcherng]

LGTM. Thanks!