What is the proper PHP function documentation format?

Question

PHP documentation is one wild animal, even the underscore_vsCamelCase styling isn't this varied. So given all the types of PHP documentation I have seen so far - which is the standard? How are my functions and methods supposed to be marked up so that the majority of IDE's and documentation libraries can read them?

In the below examples the (type) is one of:

• bool
• int
• array
• object
• string
• float

and the name is just the name of the param variable (like $values)

/*
 * Function name
 *
 * what the function does
 *
 * @param (type) about this param
 * @return (type)
 */
function example((name))

/*
 * What the function does
 *
 * @param (name) about this param
 * @return (name)
 */
function example((name))

/**
 * Function name
 *
 * what the function does
 *
 * @param (type) (name) about this param
 * @return (type) (name)
 */
function example((name))

/**
 * Function name
 * what the function does
 *
 * Parameters:
 *     (name) - about this param
 */
function example((name))

Answer 1

There is no official, according to Hoyle, comment style. The closest you'll find is the Zend Framework's coding guidelines. Zend Framework is produced by Zend, which is deeply involved in the creation of PHP, so you could argue that their coding guidelines are the ones that should be followed.

It could also be argued that any comment that takes the form

/** <--- starts with
*/  <--- ends with

Is an "official" documentation format, as these will be parsed and made available via the reflection API. Many people leverage this, and the PHPDoc format to produce an official-ish comment format.

Answer 2

Many people use PHPdoc as the standard.

Answer 3

I think PHPDoc is pretty much standard. Also your question was asked before (which maybe gives you some more ideas).

Answer 4

It may be worth taking a look at doxygen. It has multi-language support and standard input format.