问题
For ActionScript 2, I've used NaturalDocs. However it has pretty poor support for PHP. I've looked so far at doxygen and 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.
回答1:
ApiGen
http://apigen.org/
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.
DocBlox
http://www.docblox-project.org/
PHP 5.3 compatible API Documentation generator aimed at projects of all sizes and Continuous Integration.
able to fully parse and transform Zend Framework 2
回答2:
There are two well-known and often-used tool that can generate API doc from docblocks :
- 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.
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
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 ;-)
Also, there are more and more PHP tools that use php docblocks for some other purpose than documentation.
For instance, PHPUnit allows you to specify some test-related stuff using some specific tags -- see Annotations.
回答3:
PHPDoc is probably as good as you'll get it in terms of Javadoc style inline commenting. You might also want to look at PHPXRef.
回答4:
Yes, phpDocumentor (http://www.phpdoc.org/) is an acceptable standard tool for PHP autodocs. It's the de-facto standard.
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.
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.
回答5:
phpDocumentor can output in a style similar to the php.net documentation (and its built in with both smarty and non smarty layouts)
回答6:
Check out PHPDoctor http://peej.github.com/phpdoctor/, a simple yet full features Javadoc clone for PHP.
回答7:
The Wordpress code-base is documented using phpdoc tags (see this) and it's generally pretty good - it's rendered here using 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
回答8:
If ugly's a problem, I'd just switch the stylesheet for a custom one. If you don't want to overwrite the generated one, you can use a Firefox plugin like Stylish.
回答9:
You could edit the template file to add your own stylesheet to override the existing one.
来源：https://stackoverflow.com/questions/189516/automatic-php-documentation-generation