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