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.
9 Answers
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.
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.
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.
phpDocumentor can output in a style similar to the php.net documentation (and its built in with both smarty and non smarty layouts)
Check out PHPDoctor http://peej.github.com/phpdoctor/, a simple yet full features Javadoc clone for PHP.
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
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.
You could edit the template file to add your own stylesheet to override the existing one.
Related