this is mine…

I think it’s better to concentrate on the “important” Doc Blocs – which are on class Level and Method level. Well named properties (and params) can be left with a minimum of documentation. I only write more detailed documentation, when i leave the standard path of doing things.
For example i’ve got a lot of DB ids in my classes – which are always Integer greater 0 and can’t be negative. That’s why i often only put the “@return” and the “@param $param” information into my documentation, because in phpDocumentor the “getId()” getter would return void as default.

/**
* @return int
*/
public function getId() { ..

/**
* @param int $id
*/
public functiion setId() { …

easy to read and doesn’t waste much time..

Jeff Moore has written a comment to this blog entry from Travis Swicegood in which he basically says that inline-documentation of PHP-code is useless, since code is self-explanatory, especially if you have unit-tests that go with your code.
I can partl…

/**
* Do stuff
*
* @param FirstClass $object
* @return SecondClass
*/
function do_stuff($object) {
// do stuff
}

Zend Studio will know what $object is and what do_stuff() returns and provide you with code completion for $object var and returned value. Being a code completion junky I find this really helpful and because of that I document almost everything.

Detailing the format of parameters, as Matthew notes, is essential. Unlike method names, these are not always immediately obvious, and usually can be greatly helped if there are a few examples too.

In the end, however, I think PHP’s documentation is a “docblock” like standard to aspire to. After generating skeleton XML files from the source C code, manual writers then fill in lots more tasty tidbits about the PHP functions. Done correctly, its a godsend.

• Brief, one sentence summaries of what a method does. Other than that, let the code do the talking
• If any parameters are associative arrays, I like to document the array keys expected, as there’s no other way of really knowing that information unless you delve into the code itself

Also, it’s good to remember that docblocks are not just for API documentation. Many IDEs will be able to use the docblock to provide information on parameter typehints, and, using the reflection API, that same information can be used to do autodiscovery on classes used for things such as web services, MVC controllers, etc.

That said, probably the best documentation you can do is as Travis suggests: write good tests. If you write tests that test and describe the purpose of an interface, i.e., the contract it’s following, it’s much easier for a developer to go in and see how the class should be used. Furthermore, some testing frameworks, e.g. PHPUnit, have the ability to create “Agile Documentation” from tests that use the test name to generate documentation; this can often be very useful to a developer as well.

For example, here’s a doc-book-like documentation of a project I’ve released. The top-level documentation is more like a tutorial and design doc than traditional API docs, and I hope they are actually useful.

Doc-book-style documentation can still be useful, but you have to deliberately make sure to have a flow to the docs beyond the default non-flow.