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

[Dries Buytaert]

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/