[development] Let's finally document our schema already!
drupal-devel at webchick.net
Thu Aug 9 05:00:47 UTC 2007
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
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:
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
- 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. ;)
More information about the development