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