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

[Neil Drumm]

On 8/8/07, Angela Byron <drupal-devel at webchick.net> 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.

Schema information should be parsed by the API module at some point.
However, PHP code is not friendly for this. There are three options:

1. Execute the code and extract the information. Would be really easy
and really insecure.
2. Regular expressions. Only works if we strictly conform to a certain syntax.
3. PHP's tokenizer. Like regular expressions, but we have a list of
tokens and what PHP thinks they are. A bit smarter, but still fails if
someone mixes up the syntax.

None of these options is especially good.

Documentation comments would be much better. They are in code, but
have the advantage of not being code. The challenge is figuring out a
convenient and consistent comment syntax.

-- 
Neil Drumm
http://delocalizedham.com