自动生成 PHP 文档？
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/189516/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Automatic PHP Documentation Generation?
提问by davr
For ActionScript 2, I've used NaturalDocs. However it has pretty poor support for PHP. I've looked so far at doxygenand phpDocumentor, but their output is pretty ugly in my opinion. Does anyone have any experience with automatic documentation generation for PHP? I'd prefer to be able to use javadoc-style tags, they are short to write and easy to remember.
对于 ActionScript 2，我使用了NaturalDocs。但是它对 PHP 的支持很差。到目前为止，我已经查看了doxygen和phpDocumentor，但在我看来，它们的输出非常难看。有没有人有自动生成 PHP 文档的经验？我更喜欢能够使用 javadoc 样式的标签，它们易于编写且易于记忆。
回答by M A Hossain Tonu
ApiGen
基因
ApiGen has support for PHP 5.3 namespaces, packages, linking between documentation, cross referencing to PHP standard classes and general documentation, creation of highlighted source code and experimental support for PHP 5.4 traits.
ApiGen 支持 PHP 5.3 命名空间、包、文档之间的链接、交叉引用 PHP 标准类和一般文档、创建突出显示的源代码以及对 PHP 5.4 特性的实验支持。
DocBlox
DocBlox
http://www.docblox-project.org/
http://www.docblox-project.org/
PHP 5.3 compatible API Documentation generator aimed at projects of all sizes and Continuous Integration.
PHP 5.3 兼容 API 文档生成器，适用于各种规模的项目和持续集成。
able to fully parse and transform Zend Framework 2
能够完全解析和转换 Zend Framework 2
回答by Pascal MARTIN
There are two well-known and often-used tool that can generate API doc from docblocks :
有两个众所周知且经常使用的工具可以从 docblocks 生成 API doc：
- phpDocumentor, which is specific to PHP, and is probably one of the most used tool for PHP projects
- and Doxygen, which is more for C, but is used for PHP by some people.
- phpDocumentor，它是 PHP 特有的，可能是 PHP 项目最常用的工具之一
- 和Doxygen，它更多地用于 C，但被一些人用于 PHP。
About the "guidelines" : I would say it depends on your projects, but, at least, I would expect to see :
关于“指南”：我会说这取决于您的项目，但至少，我希望看到：
- a description of what the method/function does
- parameters, with
@param type name description of the parameter - return value, with
@return type description of the return value - exceptions, with
@throws type description of the exception that can be thrown
- 方法/功能做什么的描述
- 参数，与
@param type name description of the parameter - 返回值，与
@return type description of the return value - 例外，与
@throws type description of the exception that can be thrown
A great thing being that recent IDE (like Eclipse PDT, for instance), can read and interpret those markers, to provide hints when you're coding ;-)
一个很棒的事情是最近的 IDE （例如Eclipse PDT）可以读取和解释这些标记，以便在您编码时提供提示；-)
Also, there are more and more PHP tools that use php docblocks for some other purpose than documentation.
此外，越来越多的 PHP 工具将 php docblocks 用于文档以外的其他目的。
For instance, PHPUnit allows you to specify some test-related stuff using some specific tags -- see Annotations.
例如，PHPUnit 允许您使用一些特定的标签来指定一些与测试相关的内容——请参阅Annotations。
回答by Kornel Kisielewicz
回答by Alan Storm
Yes, phpDocumentor (http://www.phpdoc.org/) is an acceptable standard tool for PHP autodocs. It's the de-facto standard.
是的，phpDocumentor ( http://www.phpdoc.org/) 是 PHP 自动文档可接受的标准工具。这是事实上的标准。
It's acceptable to follow the general JavaDoc guidelines for code when documenting PHP code. However, you're going to run into cases where that's not enough because PHP and Java are different languages.
在记录 PHP 代码时遵循通用的 JavaDoc 代码指南是可以接受的。但是，您会遇到这样的情况，因为 PHP 和 Java 是不同的语言。
For example, PHP functions have no return type and it's inevitable (and sometimes desirable) for a function to return one type with one context, and another type with in a second context. JavaDoc guidelines aren't going to help with that, because it's impossible to do in Java.
例如，PHP 函数没有返回类型，并且函数在一个上下文中返回一种类型，而在第二个上下文中返回另一种类型是不可避免的（有时是可取的）。JavaDoc 指南对此无济于事，因为在 Java 中这是不可能的。
回答by Paul James
Check out PHPDoctor http://peej.github.com/phpdoctor/, a simple yet full features Javadoc clone for PHP.
查看 PHPDoctor http://peej.github.com/phpdoctor/，这是一个用于 PHP 的简单但功能齐全的 Javadoc 克隆。
回答by ólafur Waage
phpDocumentor can output in a style similar to the php.net documentation (and its built in with both smarty and non smarty layouts)
phpDocumentor 可以以类似于 php.net 文档的样式输出（并且它内置了 smarty 和 non smarty 布局）
回答by cori
The Wordpress code-base is documented using phpdoc tags (see this) and it's generally pretty good - it's rendered hereusing phpDocumentor.
Wordpress 代码库使用 phpdoc 标签（请参阅此）进行记录，并且它通常非常好 - 它在此处使用phpDocumentor呈现。
Most of the code that I write that's substantial enough that I need to think about autogenerating docs for is done in .Net, so I can't give much of a documentation writer's perspective though
我编写的大部分代码都足够丰富，以至于我需要考虑自动生成文档是在 .Net 中完成的，所以我不能给出太多文档作者的观点
回答by Aupajo
回答by Darryl Hein
You could edit the template file to add your own stylesheet to override the existing one.
您可以编辑模板文件以添加您自己的样式表来覆盖现有的样式表。
