Documentation style

Question

I'm a PHP web developer, who is looking for a well proven method for writing a good documentation (aka docblock).

There are several documentation styles, for instance:

• The descriptive but not categorized (#1):

/**
 *  Element name: class, function, variable etc. (Optional)
 *  
 *  Short description.
 *
 *  Long description.
 */

• The categorized (#2):

/**
 *  Function name
 *
 *  @param $foo
 *  @return bar
 */

• The template-like (#3):

/**
 **********************
 * NAME:    Func_Name
 * DESC:    Does A Lot
 * RETurn:  number
 * NOTES: foo bar foo...
 **********************
 */

• Variations of the aforementioned methods.

But which documentation style should I adopt?

I assume that different documentation styles should be used for different language elements:
Functions perhaps should use the #2 method,
while a class should use the #1 method.

An inline code may be documented this way (#5):

// short description
// of
// what the following code does.

I know phpDocumentor, but dislike the idea of learning how to use it.
It seems ridiculous to learn how to use something like phpDocumentor just so I could document my code.
(although I appreciate any open-source project, including phpDocumentor)

Answer 1

Others will probably tell you more specific stuff about PHP.

However, I would argue that the most important thing to figure out is "who is going to read this and when". If you are writing some major API that you expect a lot of people to use and read, you need to offer a complete specification. A nice formal style that shows clearly what the parameters are, what the return values are, etc., may almost be mandatory.

If you are not writing a world-class API but rather internal code, think about your readers. Most people who are ever going to read this are going to gloss through the code. They're going to instantiate a class or call a method to accomplish something, and they wouldn't care two cents about everything that they can probably figure out on their own. You're going to get only a second or two of attention while they skimming, and you have to make the best use of this.

In these cases, a complete description, a full parameter listing, and so on are just going to be "visual noise". If you actually write something surprising or unique or important, it maybe missed. so you are better opting for just documenting what is unique, and not documenting otherwise. The presence of documentation would then be indicative to your reader that they actually want to read, rather than notice things that they expect otherwise.

Beyond that, I would argue that you should always carefully design your class and especially your function so that nobody needs to read the documentation. If somebody needs to read "the short description" to know what your function does or what it takes, you've done a bad job of naming it or distinguishing it from others. Documentation should be a last resort, for conveying things that there is just no way to make obvious in the signature.