如何在PHPDoc中记录多个变量声明

Question

我将使用简短语法来定义类的成员变量，因此不需要使用传统的格式：

private $a;
private $b;
private $c;

我使用

private
    $a,
    $b,
    $c;

现在我使用PHPDoc来告诉IDE每个成员的类型，就像这样：

/** @var classA */
private $a;
/** @var classB */
private $b;
/** @var classC */
private $c;

然而，这种方法在使用短语法时不起作用：

private
    /** @var classA */
    $a,
    /** @var classB */
    $b,
    /** @var classC */
    $c;

我做错了什么？

- John

---

如果PHPDoc支持记录短语法声明，我会感到惊讶。难道你不能手写它们吗？ - gandaliter

这是我目前正在做的事情，但当有许多成员变量时，它会变得混乱，我希望有一些替代语法。 - John

Answer 1

很抱歉，我要告诉你这是做不到的。PHPDoc并不像你想象中那么智能，但如果没有它，地球上的生活几乎是不可能的。

此外，当人们停止遵循PSR规范（例如声明多个属性语句）时，事情通常开始变得混乱。所以，不要重复发明轮子，如果您不喜欢通常被接受的方式-坚持下去，您很快就会克服这个问题。

说真的...

- Ian Bytchek

---

我不明白为什么在一个语句中声明多个属性被认为是不好的实践。这样做可以使代码更清晰，更易于阅读，因为您可以将变量分组等。在像C++这样的语言中，您被迫以这种方式进行声明（例如，在单个“private:”标签下放置私有变量等）。无论如何，感谢您的回答 :) - John

哈哈，这个主题比炸药还要爆炸。PSR是上天赐予的礼物！它为一种非常宽容的语言增加了很好的结构层次。许多人不喜欢别人如何编写他们的代码，但许多人会妥协，以便看到其他人以与自己相同的方式编写代码。这使每个人的生活在某些时候更加轻松。 - Ian Bytchek

除了 PSR-2 之外，PSR-12（扩展编码风格）还规定您不能在一个语句中声明多个属性。详情请参见：https://www.php-fig.org/psr/psr-12/#43-properties-and-constants。 - MAChitgarha

Answer 2

实际上，phpDocumentor 2.x 支持复合声明，尽管只使用一个文档块而不是多个 -- https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/var.html#var 请注意，如果您没有得到预期的文档结果，可能是一个错误（例如这里显示的错误 -- phpDoc @var for compound statement isn't displayed correctly）。

- ashnazg

---

请展示如何按照 phpdoc.org 链接的方式编写语法。不幸的是，该链接已经失效，因此我无法找到正确的语法。 - Robin Bastiaan

@RobinBastiaan 链接已更新。 - ashnazg

Answer 3

如果你正在查看类似的类型；例如：

/** @var string */
private $stringVariable;

/** @var string */
private $stringVariable2;

/** @var string */
private $anotherVariable;

/** @var string */
private $andMoreStringTypes;

当然，您可以为每个规则使用 /** @var string */ - 但您也可以使用文档块模板，如下所示：

/**#@+
 * @var string
 */
private $stringVariable;
private $stringVariable2;
private $anotherVariable;
private $andMoreStringTypes;
/**#@-*/

- Rob

---

我找不到任何关于这个语法的官方文档，如果你有的话，能否在这里提供链接，那就太好了 :) - Alexander Schranz

@AlexanderSchranz 这里仍然有一个参考链接：https://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.docblocktemplate - 但是看起来它已经被弃用了。尽管如此，在大多数IDE中它仍然能够工作。 - Rob