Question

phpDoc是否支持自定义标签？我想使用@untested标记尚未测试的代码。怎么办呢？

Answer 1

为什么不使用{/ 3}}标记

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

或者，如果您不希望此信息包含在您的文档中，则可以使用内联@todo标记，如下所示：

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

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

Answer 2

出于价值考虑，PSR-5（截至2020年5月仍在草案中）允许自定义标签，前提是您为它们添加了项目或组织特定的名称：

>

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

这些标签或注释必须通过以下任一方式提供名称空间

使用PHP样式的名称空间或以在标签名称前加上单个供应商名称，然后加上连字符。

...

以供应商名称和连字符开头的标记名称示例：

@phpdoc-event transformer.transform.pre

因此，假设PSR-5被接受，似乎您将被允许做类似@myproject-untested的事情。尽管即使接受了PSR-5，也无法保证phpDoc工具将支持一种定义这些自定义标签的方法。

phpDoc中是否可以使用自定义标签？

2 个答案: