如何在重载方法中使用phpDoc?

因为您允许可变长度参数,所以有两种方法可以做到这一点。

我只列出允许的参数是参数。

/**
 * @param mixed $arg1 ... description
 * @param mixed $arg2 ... description
 * @param mixed $arg3 ... description
 */
 public function __construct() {}

或者我会简单地用一些例子来解释。

/**
 * Explanation of different expected argument combinations.
 */
public function __construct() {}

另一种选择是,由于只有一个示例具有多个参数,因此只需在方法签名中定义参数,使最后2个参数成为可选的。这样地:

/**
 * @param mixed $arg1 ...
 * @param int $arg2 ...
 * @param int $arg3 ...
 */
public function __construct($arg1, $arg2 = null, $arg3 = null) {}

只是我的观点,但是你不应该首先有多个构造器-你的构造器将充满if/else阶梯,这真的不是一个好主意,特别是对于一些轻量级的东西,比如颜色的表示。

我强烈建议您尝试以下方法:

class Color
{
    protected function __construct($r, $g, $b)
    { ... }

    public static function fromHex($hex) {
        return new Color(...);
    }

    public static function fromRGB($r, $g, $b) { ... }

    public static function fromArray(array $rgb) { ... }

    ...
}

现在,在消费者代码中,不是像下面这样有点神秘和模棱两可的构造函数调用:

$a = new Color(0,0,0);
$b = new Color('#000000');

相反,您可以使用更清晰、语义更明确的消费者代码,如:

$a = Color::fromRGB(0,0,0);
$b = Color::fromHex('#000000');

对于阅读使用者代码的人来说,这可能更有意义,它消除了使不明确的构造函数工作所需的逻辑,并且作为额外的好处(如果您使用的是诸如phpstorm之类的IDE),您可以通过所有的检查。如果您运行的是文档生成器,这还可以确保所有选项都是单独记录的,而不是在口头描述中集中在一起。

注意,我声明了构造函数 protected -这是一个个人偏好,但是如果我要有多个静态工厂方法,我宁愿看到那些在消费者代码中持续使用的方法,而不是有时看到 Color::fromRGB(...) 其他时候 new Color(...) .

我觉得最好用这个 @method 类/接口的注释,它声明重载方法。这个问题对我来说也很有趣。

 /**
  * @method void setValue(int $value)
  * @method void setValue(string $value)
  * @method void setValue(string $value, int $startFrom)
  */
 class Example
 {
     public function setValue($arg1, $arg2)
     {
        // ...
     }
 }

见 http://phpdoc.org/docs/latest/references/phpdoc/tags/method.html

我不知道用PHPDOC做这件事的优雅方式。phpDoc注释/api格式基于 Javadoc 格式。Javadoc没有一个特征集来支持这一点,因为在Java中,如果您希望一个方法具有可变数量的参数,则为每个变量重新声明方法原型。

public double foo() {
}

public double foo(double my_param) {        
}

所以,我的性能偏好是

/**
 * My General description
 * 
 * Here explain what each argument combination can do
 * @param mixed $arg1 can be array, string, hex as string, or int 
 * @param int $arg2 if arg1 is int, then this is etc, otherwise optional 
 * @param int $arg3 if ar1 is int, then this is etc, otherwise optional
 */

但对于各种自动文档工具来说,这可能不太好。

按照霍伊尔的方式来完成这一点可以在 phpDoc site .