phpDoc 中是否可以自定义标签？答案

【问题标题】：Are custom tags possible in phpDoc?phpDoc 中是否可以自定义标签？
【发布时间】：2016-08-10 11:42:42
【问题描述】：

phpDoc 支持自定义标签吗？我想使用@untested 标记尚未测试的代码。如何做到这一点？

【问题讨论】：

你试过用谷歌搜索吗？ onomatopoeia.pinkgothic.com/article/…
@rokas 感谢 2009 年的文章。看起来phpDoc不支持标签而不进入并更改其代码。
同时这似乎是可能的。看看：github.com/phpDocumentor/ReflectionDocBlock/blob/master/…

【解决方案1】：

不管怎样，PSR-5（截至 2020 年 5 月仍处于草案阶段）允许自定义标签只要您在它们前面加上项目或组织特定的名称：

为了支持注释，可以引入一组专门为单个应用程序或应用程序子集设计的标签（因此本规范未涵盖）。

这些标签或注解必须提供一个命名空间

在标签名称前加上 PHP 风格的命名空间，或在标签名称前加上一个供应商名称，后跟一个连字符。

...

以供应商名称和连字符为前缀的标签名称示例：

@phpdoc-event transformer.transform.pre

因此，假设 PSR-5 被接受，您似乎可以执行@myproject-untested 之类的操作。无法保证 phpDoc 工具将支持定义这些自定义标签的方式，即使 PSR-5 被接受。

【讨论】：

【解决方案2】：

你为什么不直接使用@todo标签

 /**
  * Here comes the summary
  *
  * @todo this code has to be tested
  *
  * @return boolean Returns something
  */
 function someFunction()
 {
     <...>
 }

或者，如果您不希望这些信息包含在您的文档中，您可以像这样使用内联 @internal 标签：

 /**
  * Here comes the summary
  *
  * {@internal this code has to be tested }}
  *
  * @return boolean Returns something
  */
 function someFunction()
 {
     <...>
 }

我认为添加自定义标签不是一个好主意。虽然 PHPDoc 仍然是非正式的，但很可能在不久的将来会成为正式的标准。所以如果我是你，我会尽可能地使用官方标签。

【讨论】：