PHPDoc:用可变数量的参数记录函数

Question

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

也许是这样的？

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

注意:作为一般规则，我认为应该尽可能避免这种类型的事情。话虽这么说，但最好还是记录其余少数无法避免的情况。

Answer 1

如果您使用可变数量的参数并且还使用 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，我建议使用此方法