PHPDoc: документирование функции с переменным числом аргументов

Каков рекомендуемый метод документирования метода класса, который принимает переменное количество аргументов?

Может быть, что-то вроде этого?

<?php

class Foo {
    /**
     * Calculates the sum of all the arguments.
     *
     * @param mixed [$arg1, $arg2, ...]
     *
     * @return float the calculated sum
     */
    public static function sum() {
        return array_sum(func_get_args());
    }
}

Примечание. Как правило, я считаю, что такого рода вещи следует избегать, когда это возможно. При этом было бы неплохо документировать оставшиеся несколько случаев, когда этого нельзя избежать.

Ответ 1

/**
 * @param mixed $numbers,... Description
 */
Public function sum ($numbers)

В методе $numbers не будут использоваться.

Ответ 2

Если вы используете переменное количество аргументов, а также используя PHP >= 5.6, то вы можете использовать вариативные функции (допускающие переменное количество аргументов), которые по-прежнему соответствуют синтаксису PHPDoc ,..., уже упомянутому, и PHPStorm будет интерпретировать документы правильно. Использование вариационных функций исключает необходимость func_get_args() для захвата аргументов в массив.

/**
 * @param mixed $args,... Explainatorium!
 */
function variadiculous(...$args) {
    // NOTE: $args === func_get_args()
    foreach ( $args as $arg ) {
        /* do work */
    }
}

PHPStorm автоматически сгенерирует документы как @param array $args, потому что технически, когда внутри функции variadiculous is_array($args) истинно. Я изменяю его, чтобы читать @param mixed $args,..., как указано выше, и когда я использую горячую клавишу для отображения сигнатуры функции из другого места в моем коде PHPStorm отображает variadiculous($args : ...array|mixed) - я рекомендую использовать этот метод, если вы используете PHP >= 5.6

Ответ 3

В случае ... синтаксис, PHPStorm 2017.1 использует:

/**
 * @param Type[] ...$values One or more values.
 */
public function func(Type ...$values) {
    // ...
}