【发布时间】：2014-12-20 11:00:07
【问题描述】：
如果我只想从父级继承所有文档，那么 phpDocumentor 中 @inheritDoc 的正确语法是什么？也许不止一种语法是正确的？
@inheritDoc{@inheritDoc}@inheritdoc{@inheritdoc}
我认为文档很模糊。 PhpStorm 似乎支持所有这些，但也许我无法使用某些语法生成文档？
【问题讨论】：
标签： php phpdoc inheritdoc
【发布时间】：2014-12-20 11:00:07
【问题描述】：
子元素应该自动继承其父文档块的几乎所有内容不需要这个标签。否则，您的所有实现方法都必须重新记录，而无法从原始接口的文档中获得任何信息。
简单地说，没有文档块的继承元素应该自动从其父文档块继承所有内容。
@inheritdoc 标记的唯一目的是帮助您从父文档块导入一个 内容——该父文档的详细说明。孩子不应该有这个可用的唯一原因是孩子继续前进并拥有自己的文档块。现在，子 应该 仍然从其父 docblock 继承几乎所有内容，而不必复制它... 除了父的长描述。 如果子文档块出于某种原因选择拥有自己的文档块，并且你仍然想要继承父文档的长描述，那么你把子文档块中的@inheritdoc 确定父长描述出现的位置。因此，孩子可以有自己的简短描述和详细描述，并且仍然还在与孩子详细描述相关的指定位置中包含其父母的详细描述。 这是这个标签诞生的唯一原因 :-)
关于 IDE 自动补全，我不能说我在 IDE 中看到了关于这个标签的一致行为。此外，我看到一些项目假设这个标签是从父文档块继承信息的原因。
【讨论】：
-
我认为答案大部分都在那里，但您应该澄清您的意思是 {@inheritDoc}。大括号澄清它是内联的，这只会像你说的那样带来长描述。请参阅此处关于 {@inheritdoc} 的注释，它是误用，以及新的 @inheritDoc 标签 phpdoc.org/docs/latest/guides/…。
-
@inheritDoc在遗留代码库中很方便，可以告诉读者故意丢失了文档。文档生成器不需要，但人类在编辑器/ Github 上查看代码需要。 （这显然也是标准草案中的called out explicitly。）
我对 IDE 支持一无所知，但 documentation 将其拼写为 {@inheritDoc}。
【讨论】：
-
文档也将其拼写为
{@inheritdoc}manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/… -
除了将 docs.phpdoc.org 文档拼写为
{@inheritDoc}之外，它还解决了使用此标签将 DocBlock 的 all 内容显式替换为父/接口（参见红色的“重要”段落），并区分包含父级描述的原始内联{@inheritDoc}标签和替换整个内容的新/潜在@inheritDoc标签（并且已经在一些客户以这种方式使用）。