Documenting CakePHP components

Question

I'm mostly concerned with documenting Controller actions, e.g http://foo.bar/app/thing/action/param. How would you recommend documenting these? I'm less interested in the method of generating the documentation (e.g. phpdoc or doxygen) and more a style of doing it. Should I list the parameters and return values as if I were documenting any other method?

Answer 1

In terms of format, I typically follow the same (well, similar) convention used by the CakePHP project itself (http://book.cakephp.org/view/509/Coding-Standards#Commenting-code-601). It's similar enough to JavaDoc that I found it easy to adopt and works nicely with the phpDoc engine. I do tend to include @param values as well as @return. I often find it helpful to provide a bit of additional explanation for acceptable/expected values.