Status of 1.3 Code Documentation and RFC

[Chris Travers <..hidden..>]

Hi all;

One thing that a tremendous amount of effort has gone into in 1.3 is
code documentation both with the old code routines and the new ones.
This documentation is subject to its own set of tests to determine
coverage within certain parameters, and so forth, but it will need to
be reviewed again.  I can say that this is a very serious improvement
over past releases.

Code documentation takes two forms:
1)  API reference, done in POD
2)  Appropriate, collaborative comments

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.

One interesting feature is that the POD gets turned into man pages
during the make test process.....

I'd like to hear feedback on these topics.

Best Wishes,
Chris Travers