documenting cakephp project

Question

I'm working on a couple of CakePhp projects these days and I was wondering how I should document them. I'm used with ruby on rails where documenting is made easy with the help of the framework.

Is there anything like this in CakePhp? I'm looking at the documentation of the framework and I can't find anything about that. If it's not part of the framework, what would be the proper way to document my project?

Answer 1

You should try the Api Generator plugin (introduced here) used to power the official CakePHP API.

It uses the Reflection class (available in PHP 5.2 and above) to dynamically introspect your code's docblock comments meaning you don't have to regenerate your documentation for every change you make.

There are also a few extra features such as search indexing, calculating documentation coverage of your code, and allowing the use of Markdown in your docblock comments to generate HTML in your documentation.

You can always use generic solutions that apply to any PHP codebase instead, such as phpDocumentor or doxygen.

You will need to add docblocks to your code with the appropriate tags for any of these solutions to work (some IDEs can generate these for you). The core CakePHP code (and associated documentation) can be used as a good example of what is required.

A few subtle standards I have noticed the CakePHP team use when documenting code:

1. Never indent the docblock comment, even inside a class. This allows you to scroll through code scanning by docblock, and also allows you the full horizontal width of each line to type (usually around 100 characters).
2. Finish every sentence with a full stop (or period) as this acts as a good signal to let you know if each part of the documentation is complete and well thought out.