Automatic PHP Documentation Generation?

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.

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

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.