Re: Status of 1.3 Code Documentation and RFC

[Chris Travers <..hidden..>]

On Thu, May 19, 2011 at 12:02 PM, Luke <..hidden..> wrote:

>> The API reference currently covers the perl modules, but not the
>> workflow scripts, or the SQL functions.  The workflow scripts it isn't
>> clear to me what sorts of documentation on the functions there is
>> helpful.  The SQL functions are usually short enough that most of them
>> are obvious as to what they are supposed to do, and it isn't clear
>> where/when SQL COMMENT ON statements are helpful there.  One option
>> may be that for longer functions we may want to have a brief
>> description of the function as a comment attached to it.
>
> I would want to see a comment at the head of the function,
> specifying expected
> parameters, expected returns, expected globals altered, and
> purpose of function.

If we use SQL COMMENT ON for that, they'd have to follow the function
because we can't attach a comment to a function that doesn't exist.
The advantage to doing that is that auto-documentation tools can see
the comments and use them in the document generation.

If it were only up to me, I'd use SQL COMMENT ON for these comments
and sql comments (--comment) for collaborative comments just because
the tradeoff with automatic documentation generation seems favorable
to me.  But I recognize this is a tradeoff.  What do others think?

Best Wishes,
Chris Travers