[development] Let's finally document our schema already!

[Angela Byron]

Harry Slaughter, JonBob, myself, and others have tried countless  
times to come up with a workable solution for documenting our  
database schema. This either resulted in static images and so forth  
that were impossible to maintain, or trying to work around MySQL's  
comment length limitations.

However, with the Schema API, the day is saved! Joy!

Earl came up with this slick idea in the Views 2.0 schema to stick a  
'description' attribute on each field in the schema file. Drupal will  
of course ignore this, having no knowledge of what a description is,  
but human beings (and probably eventually parsers) can read this  
information in order to determine what the various fields are for.  
Additionally, the documentation is *part of the source code*, which  
means we can deny schema additions until they have documentation  
associated, just as we deny new functions without PHPDoc. And  
finally, because the descriptions are stored in t() functions, that  
means the documentation is (potentially?) translatable to other  
languages.

I've taken this idea a couple steps further (by adding table  
descriptions as well as field descriptions, and adding in foreign key  
information), and have started documenting all core schema files here:

http://drupal.org/node/164983

I'd love help from:
- Anyone at all who has some time on their hands and would like to  
learn Drupal's schema inside and out by helping to document the  
remainder of the files, using the existing patch as a guide.
- Core committers, to give a thumbs up/thumbs down to this approach  
before we dump a bunch of time into it. ;)
- Schema API folks, to give guidance, esp. on foreign key  
representation.
- Experts on the lesser-used aspects of Drupal (aggregator module,  
for instance) who can clarify what some of the fields are for.
- Testers, to make sure the patch doesn't horribly break things. ;)

Thanks!
-Angie