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

Question

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

Answer 1

为什么不直接使用 @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 仍然是非正式的，但它很可能在不久的将来成为正式标准。所以如果我是你，我会尽可能坚持使用官方标签。

Answer 2

就其价值而言，PSR-5（截至 2020 年 5 月仍处于草案阶段）允许使用自定义标签前提是您在它们前面加上项目或组织特定的名称:

In support of annotations, it is allowable to introduce a set of tags designed specifically for an individual application or subset of applications (and thus not covered by this specification).

These tags, or annotations, MUST provide a namespace by either

prefixing the tag name with a PHP-style namespace, or by prefixing the tag name with a single vendor-name followed by a hyphen.

...

Example of a tag name prefixed with a vendor name and hyphen:

@phpdoc-event transformer.transform.pre

所以假设 PSR-5 被接受，你似乎可以做类似 @myproject-untested 的事情。即使 PSR-5 被接受，也不能保证 phpDoc 工具将支持定义这些自定义标签的方法。

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

Are custom tags possible in phpDoc?

php

phpdoc