One of the great things about Debian/Ubuntu is the consistency with which system documentation is placed in /usr/share/doc/

Assuming you have a web server installed this documentation is then available at http://localhost/doc/

Comments in code are widely used and generally (but not universally) accepted as a good thing.

Databases can also accommodate comments - but these seem to be very rarely used.

I’m of the opinion that database comments are very useful.

The Drupal api module is very useful. It’s also quite strict in the formats it recognises.

If you are having trouble getting it to recognise your doc-comments make sure you are following the Drupal coding standards

http://drupal.org/coding-standards

Using doc-comments in Eclipse really helps productivity by providing lots of tool-tip help and auto completion.

A colleague recently pointed out that Eclipse can auto-complete object properties (as long as you use the @property tag). I’ve found this really helpful and have been creating objects to return pass around - and found it a vwery neat way of working.

With any sizeable project maintaining good documentation is a challenge - it’s all to easy to skimp on documentation, or to start with good intentions but allow the documentation to get out of date.

The Drupal API project allows you to set up a documentation website for your project like api.drupal.org that covers all your code.