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

[Angela Byron]

On 9-Aug-07, at 1:42 AM, Neil Drumm wrote:

> 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.

As long as it's in-line with the schema source code, it doesn't  
matter much to me what format it takes. But it **MUST** be in the  
actual source code of the .schema file, and not stored in a separate  
document (like the FAPI reference) or it will very quickly fall  
hopelessly out of date with what the code actually says (like the  
FAPI reference :P~).

In the meantime, though, we still do need the table/field  
descriptions before we can do either one, so we can still work away  
on that while we come to a consensus about the comment syntax.

Past attempts:
- http://drupal.org/node/28046: uses the MySQL COMMENT attribute,  
limited to 60 characters. We can no longer use this method, because  
we don't have actual SQL doing create table statements, and the  
character limit sucked, anyway.
- http://drupal.org/node/79874: uses a common comment format ( --  
(PK), -- (FK) -> session.sid, -- Description) to the SQL. Again,  
we're no longer storing SQL, so this isn't viable, and it also shares  
the fragile problem that regexing it out of the schema files has.

I'm having kind of a hard time making sense of this document, but I  
"think" the "Putting documentation after members" section of the  
Doxygen manual [http://www.stack.nl/~dimitri/doxygen/docblocks.html]  
seems to have a special syntax for what kind of we're trying to do:

int var; /**< Detailed description after the member */

Of course, fields and tables aren't members of objects, but they are  
"kinda sorta" the same thing. Meh, I dunno.

Open to other suggestions...

-Angie