【发布时间】：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 服务工厂，因为这些类完全在运行时生成。