自动生成PHP文档？

Question

对于ActionScript 2,我使用过NaturalDocs.但是它对PHP的支持很差.到目前为止我看过doxygen和phpDocumentor,但是我认为它们的输出非常难看.有没有人有PHP自动文档生成的经验？我更喜欢能够使用javadoc风格的标签,它们很容易编写并且易于记忆.

Answer 1

ApiGen

http://apigen.org/

ApiGen支持PHP 5.3命名空间,包,文档之间的链接,PHP标准类和一般文档的交叉引用,突出显示的源代码的创建以及PHP 5.4特性的实验支持.

DocBlox

http://www.docblox-project.org/

PHP 5.3兼容的API文档生成器,适用于各种规模和持续集成的项目.

能够完全解析和转换Zend Framework 2

Answer 2

有两个众所周知且经常使用的工具可以从docblocks生成API文档:

• phpDocumentor,特定于PHP,可能是PHP项目最常用的工具之一
• 和Doxygen,更多的是C,但有些人用于PHP.

关于"指南":我会说这取决于你的项目,但至少,我希望看到:

• 方法/功能的描述
• 参数,用 @param type name description of the parameter
• 返回值,带 @return type description of the return value
• 例外,有 @throws type description of the exception that can be thrown

最近的IDE (例如Eclipse PDT)可以读取和解释这些标记,以便在编码时提供提示,这是件好事;-)

此外,有越来越多的PHP工具将php docblock用于除文档之外的其他目的.

例如,PHPUnit允许您使用某些特定标记指定一些与测试相关的内容 - 请参阅注释.

Answer 3

在Javadoc样式内联注释方面,PHPDoc可能就像你得到的一样好.您可能还想查看PHPXRef.

Answer 4

是的,phpDocumentor(http://www.phpdoc.org/)是PHP autodocs可接受的标准工具.这是事实上的标准.

在记录PHP代码时遵循一般的JavaDoc代码指南是可以接受的.但是,你会遇到这样的情况,因为PHP和Java是不同的语言.

例如,PHP函数没有返回类型,并且函数返回一个具有一个上下文的类型并且在另一个上下文中返回另一个类型是不可避免的(有时是可取的).JavaDoc指南对此没有帮助,因为在Java中不可能做到这一点.

Answer 5

如果丑陋是一个问题，我只需将样式表切换为自定义样式表即可。如果您不想覆盖生成的插件，可以使用 Firefox 插件，例如Stylish。