php - 如何将 phpDoc 与重载方法一起使用？

Question

假设我有一个名为 Color 的 PHP 类，它的构造函数接受各种参数。

// hex color
$myColor = new Color('#FF008C');

// rgb channels
$myColor = new Color(253,15,82);

// array of rgb channels
$myColor = new Color(array(253,15,82));

// X11 color name
$myColor = new Color('lightGreen');

我应该如何使用 phpDoc 为构造函数和其他类似方法创建 API 文档？

如何使用重载方法的 phpDoc？

class Color {

    /**
     * Constructor
     * what should be here?
     */
    public function __construct() {
        /* CODE */
    }

}

Answer 1

只是我的观点，但首先你不应该有多个构造函数——你的构造函数将充满 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(...)。