PHPDoc：使用可变数量的参数记录函数

What is the recommended method for documenting a class method that accepts a variable number of arguments?

记录接受可变数量参数的类方法的推荐方法是什么?

Maybe something like this?

也许是这样的?

<?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());
    }
}

Note: As a general rule, I imagine this type of thing should be avoided where possible. That being said, it would be nice to still document the remaining few cases where it cannot be avoided.

注意:作为一般规则,我想在可能的情况下应该避免这种类型的事情。话虽这么说,仍然很难记录剩下的几个无法避免的案例。

3 个解决方案

#1

If your using a variable number of arguments and also using PHP >= 5.6 then you are able to use variadic functions (allowing variable number of arguments) which still conforms to the PHPDoc ,... syntax already mentioned and PHPStorm will interpret the docs properly as well. Using variadic functions eliminates needing func_get_args() to capture arguments into an array.

如果您使用可变数量的参数并且还使用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 will auto-generate the docs as @param array $args because technically when inside the function variadiculous is_array($args) is true. I change it to read @param mixed $args,... as above and when I use the hotkey to display a function signature from somewhere else in my code PHPStorm displays variadiculous($args : ...array|mixed) -- I recommend using this method if your using PHP >= 5.6

PHPStorm将自动生成docs @param array $ args,因为技术上在函数variadiculous is_array($ args)内部为真。我改为阅读@param mixed $ args,...如上所述,当我使用热键在我的代码中显示来自其他地方的函数签名时PHPStorm显示variadiculous($ args:... array | mixed) - I如果您使用PHP> = 5.6,建议使用此方法

#2

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

In the method, $numbers will not be used.

在该方法中,将不使用$ numbers。

#3

In the case of the ... syntax, PHPStorm 2017.1 uses:

在...语法的情况下,PHPStorm 2017.1使用:

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

#1

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

#2

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