DB dictionary

My preference is to embed this in the actual database.mysql file as discussed here: http://drupal.org/node/28046 -- for a few reasons:

1. Once the "up-front" work is done, it becomes much easier to enforce that any future database column/table additions *MUST* have comments attached to them in the .mysql file. It becomes a basic QA thing, like PHPDoc above functions.
2. #1 ensures that there will always be _some_ level of current, correct documentation attached to the database level. As opposed to now when probably 30 people have all gone and written some partial semblance of database documentation but never finished it, or it grew out of date because they didn't have a chance to maintain it, etc.
3. It's not a separate document that must be gone through and updated by someone whenever there are changes. Take the Forms API Reference, for example, which is constantly out of date.
4. Various tools can auto-generate documents like a data dictionary, E-R diagram, etc. from SQL files with embedded comments.

The way Harry and I were headed before we both got insurmountably busy was to setup the schema with table relations in the PHPMyAdmin tool, because it would create a standard set of comments to illustrate table relations. These could both be read by humans to figure out how tables fit together, and also parsed by tools to create diagrams.

What's cool about your script is that:
a) It's fairly complete
b) The coding follows a pattern so the details in it could probably be parsed out via regex and put in database.mysql like we had wanted to to begin with (note: I'd love to, but I can't volunteer for this -- I know my schedule to well :\)

IMO, developer documentation is critical. It therefore needs to be a community-managed process, and should not rely on a single individual/individuals to keep it up to date. The best way to do that is to integrate the documentation directly into core.

old issue