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

Posted 2023-02-22

【中文标题】PHPDoc：用可变数量的参数记录函数

【英文标题】：PHPDoc: Documenting a function with a variable number of arguments

【发布时间】：2013-01-08 22:02:03

【问题描述】：

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

也许是这样的？

<?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】：

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

【参考方案2】：

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

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

【讨论】：

可以在manual.phpdoc.org/htmlSmartyConverter/HandS/phpDocumentor/…找到有关“,...”语法的详细信息

Phpstorm 不理解此语法并警告参数计数

@PHPst 可以 - 至少 v10 可以。但是你必须使用 2 个参数：($number,...$numbers);

【参考方案3】：

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

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

【讨论】：

这似乎是有问题的描述，因为它暗示您应该将数组作为不正确的参数传递。

一目了然，直到您注意到紧随其后的...。

好吧，我没注意到 ;) 一个奇怪的符号

此问题已在 2018.1.7 中修复（根据 youtrack.jetbrains.com/issue/WI-29429）。现在 DocBlock 应该匹配方法签名：@param Type ...$values One or more values.

【参考方案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 块，并且取决于您在 doc 块中定位 $args 变量的方式，...$args 或 $args,... 确定您在 IDE 中获得的提示类型。

如果你有一个可选长度的函数/方法参数，我真的想要一种方法来建议你应该按名称传递给方法的值，其中它们应该具有特定的顺序被通过。

您可能会想，“只需设置默认参数，$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) 

...所以：

https://***.com/a/38275992/1290575 https://***.com/a/43622600/1290575

...是正确答案（请记住方向：...$args 或 $args,...）