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.
