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＆gt; =，我建议使用此方法5.6

Answer 2

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

在该方法中，不会使用$ numbers。

Answer 3

对于... syntax，PHPStorm 2017.1使用：

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

Answer 4

值得注意的是，使用doc块，例如：

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

...似乎您可以传递Type的数组，例如

Foo()->func([Type, Type, Type])

...这显然引发了致命错误。

位置：

Foo()->func(...[Type, Type, Type])

...没有，因为您在方法调用时对其进行了破坏。

无论如何，这里的重点是我正在试验PHPStorm如何处理doc块，并取决于使用$args或{来定向doc块中的...$args变量的方式。 {1}}确定您在IDE中返回的提示类型。

如果您具有可选长度的函数/方法参数，并且应该按特定顺序排列它们，那么我真的很想一种方法来建议您应按名称将值传递给以下示例图像中的方法被通过。

您可能会认为，“只需设置默认参数$args,...”通常是有道理的，但在某些情况下

伪示例：

$arg1 = 'default', $arg2 = true

...如此：

...是正确的答案（只需记住方向：/** * @param int ...$args Hour, Minute, Second, Timezone, $arg [, ...$args] */ public static function createA(int ...$args) {} /** * @param int $args,... Hour, Minute, Second, Timezone, $arg [, ...$args] */ public static function createB(int ...$args) {} /** * @param int[]|int $args,... Hour, Minute, Second, Timezone, $arg [, ...$args] */ public static function createC(int ...$args) {}或...$args）

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

4 个答案: