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

[Moshe Weitzman]

we could, but it isn't ideal. this will necessitate that every table
and field gets defined twice - in php array and phpdoc. true that only
the name is duplicated but still - the chance for out of sync
increases.

anyway, we don't need this on api.drupal.org. people who want a data
dictionary just install schema module and they have a data dictionary
exactly matching their current site. as barry said, the data
dictionary presentation is already done.

On 8/9/07, Dries Buytaert <dries.buytaert at gmail.com> wrote:
>
> On 09 Aug 2007, at 07:00, Angela Byron wrote:
> > 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.
>
> Is there a reason why we can't use PHPdoc for this?  (I'm not really
> keen on having to execute random PHP code on api.drupal.org.)
>
> --
> Dries Buytaert  ::  http://www.buytaert.net/
>
>