PHPDoc 的现状是什么？

Question

我以前从未关注过文档化我的代码，但最近我开始参与一个开源项目，对文档的需求变得越来越迫切。显然，“武器选择”是PHPDoc，但是...... 我实际上找不到PHPDoc标准的单一规范。有一个维基百科条目列出了一些属性，还有phpDocumentor项目，它据说有更全面的字典，但让我困惑的是：PHPDoc的权威指南在哪里？是否有一个单一的标准，或者由所有这些众多的phpDocumentor模仿品来扩展PHPDoc“标准”（如果有）到他们认为合适的任何地方。 如果我们假设phpDocumentor是创建和维护PHPDoc标准的地方，那么情况看起来相当严峻，因为项目网站已经死亡了将近4年。更让我困惑的是，大约一个月前，在phpDocumentor的Pear网站上突然出现了一个版本1.4.4。

我知道这里有很多更聪明、更有知识的人，所以我想知道。PHPDoc是什么情况？是否有一个单一的权威机构制定标准？它有多可靠？它有未来吗，还是我们正在处理一个僵尸，所有希望都已经失去了...

谢谢， Ivo

- Ivo Sabev

---

不是一个针对 Stack Overflow 的问题 - user557846

@Dagon - 我不同意。这属于编程行业特有的实用且可回答的问题。 - Joseph Silber

参考一下，网站有一段时间没有更新并不意味着该网站（或者该项目）已经“死亡”。可能只是因为在过去的三年里没有需要推出新版本，因为该软件已经能够很好地完成其任务。 - cHao

@cHao：问题在于它不支持PHP 5.3的特性。文档生成器也很慢，使用起来很麻烦。 - GordonM

Answer 1

根据维基百科的说法（它已经死了）。

PhpDoc标签的规范曾经是PhpDocumentor文档中列出的内容。但正如我所说，它已经死了。由于DocBlox似乎填补了PhpDocumentor留下的空白，我建议使用DocBlox文档作为编写PhpDoc注释的基础。

我希望Netbeans 7.1会引入DocBlox支持，因为它更好用。它支持PHP 5.3，并且正在积极维护。

- GordonM

---

感谢您的评论。我知道有许多文档生成器，但它们似乎都是在 PHPDoc 基础上进行扩展，所以我一直暗自希望会有一个单一的标准，但也许并没有吧。 我目前个人选择的生成器是- http://apigen.org. - Ivo Sabev

如果它们似乎都扩展了phpDoc......那应该告诉你一些事情。也就是说，有一个主要的文档注释标准。你使用哪个系统可能会改变，但注释基本上是相同的。 - cHao

我给phpdocumentor的几位开发者发送了电子邮件，他们告诉我该项目并未“死亡”，但不会进行增强以获得php 5.3功能（维基百科文章也相应更新，不再将该项目列为已停止）。我同意@IvoSabev的看法，apigen是我新的个人最爱。 - William

Answer 2

截至2013年8月，PHP框架互操作性小组开始起草PHPDoc的正式规范（PSR）。目前的PHPDoc标准提案是草案PSR5：https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md。

当前的草案更新了规范以适应PHP 5.3+，以及其他已发生的变化。我认为期望是这个php注释标准将在多个文档生成器中被采用。

- Amgine

Answer 3

这个问题已经有点老了，但为了提供信息，我应该补充一下，DocBlox已经与PhpDocumentor合并。

宣布phpDocumentor 2 - 老的（phpDocumentor）和新的（DocBlox）的合并。

随着phpDocumentor（2.0.0a1）的第一个alpha版本发布，“Responsive”默认模板采用了新的页面布局，以及原始DocBlox模板提供的有用的布局改进（仍然可用），而旧的phpDocumentor模板将会被淘汰。在http://demo.phpdoc.org/Responsive/index.html上探索这个新模板。

=> http://www.docblox-project.org/2012/03/docblox-is-unmasked-it-is-really-phpdocumentor-2/

PHPDoc又回来了。=)

- jonathancardoso