你可以为一个类创建一个外部 PHPdoc 吗？

Posted 2023-02-19

【中文标题】你可以为一个类创建一个外部 PHPdoc 吗？

【英文标题】：Can you create an external PHPdoc for a class?

【发布时间】：2016-12-21 05:30:03

【问题描述】：

假设我有以下内容

class Something extends ClassWithMagicMethods

通常我会为我知道存在的任何属性添加一个文档块，即使通过魔术方法访问也是如此

/**
 * @property string $someVar
 * @method SomeClass getSomeClass()
 */
class Something extends ClassWithMagicMethods

这很好用，但我想知道我们是否可以将该 docblock 与类的定义分开。两种可能的用例：

不包含 docblock 但我希望从我的 IDE 自动完成的第三方包 - 我希望能够在某处添加我自己的 docblock。 扩展系统 - 在定义扩展的文件中，我想记录此扩展添加到类的新属性。

我知道我可以在技术上创建一个虚拟的 ide_helper.php 文件，该文件永远不会真正运行 - 只是由 IDE 索引 - 不幸的是，这会导致任何体面的 IDE 抱怨我不想要的重复声明，因为它也会使代码导航较慢。

那么 - 是否可以通过在类定义外部组合多个文档块来记录 PHP 类？

我在 SO 上得出的大多数结果都只是引用了记录未知类型的文档，你在哪里使用它们，这不是我需要的。即：

/** @var Something $something */
$something = FactoryMethodThing::create('Something');

【问题讨论】：

不，大多数文档块解析器与类一起读取文档块。公平地说，不错的 IDE 不需要文档块来提供自动完成功能。如果 IDE 能够对代码进行标记和词法分析（例如 phpstorm 这样做），则可以直接从代码中提供自动完成功能。此外，为不存在的类读取文档块是没有意义的。

@Sherif 我使用 PHPstorm，但我明确地谈论了实际上不在代码中的动态属性和方法（一个很好的例子是没有定义属性的 ORM 类）。

我可以理解，但是为代码中不存在的类放置一个 doc 块有什么意义？通常文档块与类一起读取，因为解析器可以将文档块与该类相关联。在实践中试图将它们分开是没有意义的。

此外，任何在代码中动态生成的属性都将无法记录，因为它们依赖于了解有关运行时的信息。 doc 块通常基于不需要任何运行时知识的静态分析规则。很抱歉成为坏消息的暴露者，但这个想法在实践中并不是好兆头。

你跳过了我上面提到的两个用例，一个没有记录的第三方包（想想作曲家），或者一个扩展系统，所以原始类不知道关于您的扩展正在添加的新属性，但扩展显然是这样做的（我不是指classB extends classA，我指的是基于注入的扩展系统），这样的事情有有效的用例。另一个很好的例子是记录 Guzzle 服务工厂，因为这些类完全在运行时生成。

【参考方案1】：

看看这对你有没有帮助：

phpdoc -d path/to/my/project -f path/to/an/additional/file -t path/to/my/output/folder

来源：http://docs.phpdoc.org/guides/running-phpdocumentor.html