websites that work for you
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/
But to keep filesize down - many files are compressed and have to be decompressed before you can read them.
The browser can actually do that compression on the fly - if it receives the right headers - what it needs to be told is that the content is compressed plain text.
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.
It's often hard to determine the exact meaning of a column - maybe it would be ideal to rename the column but you don't want to risk breaking code.
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 reconise your doc-comments make sure you are following the Drupal 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.
