Widely accepted methods for documenting PHP source code in an auto-doc way?

Question

I'm new to PHP, and my current job requires me to pick up the language at an extremely quick pace.

I'm a documentation stickler. I even like to write documentation. I'm familiar with accepted documentation syntax and tools for a handful of languages.

This is not the case for PHP.

I know there are always multiple methods for writing doc-able source code comments, and there are usually various tools for each language. However, I'm in an environment that hasn't mandated a standard way of commenting, nor a standard PHP autodoc tool. That gives me freedom to choose, and a bit of paralysis-by-analysis to go along with it.

Is phpDocumentor (http://www.phpdoc.org/) an acceptable standard tool for PHP autodocs?

Is it acceptable to follow the general JavaDoc guidelines for code when documenting PHP code?

Answer 1

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.

Answer 2

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.

Answer 3

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

Answer 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.