Leon Rochester and Tracy Usher made the presentation to most of the Documentation Task Force [Heather Kelly (chair), Joanne Bogart, Karl Young, Alex Schlessinger and Mark Strickman were present] and a host of other interested parties.
The review proceeded more or less according to plan. Tracy gave an overview of the structure of TkrRecon, referring to this diagram. A terse version of his explanation can be found in the package's mainpage. Then Leon took over to describe the status of the TkrRecon documentation and to guide us through those parts which have been done.
The TkrRecon mainpage contains all recommended components: package overview, literal inclusion of requirements file, and reference to release.notes. [..however when I build the doxygen documentation locally with vcmt this reference doesn't produce a link as it should. ed.] Leon spent a significant amount of time reconstructing release.notes after the fact for about 30 releases of the package. The format he used (tag, date, tagger, description) seems to have all the right stuff and should be made part of the DocTF recommendations. There was general dismay at the fact that there is no automatic mechanism to elicit a comment from the tagger at rtag time. According to CVS documentation, it ought to be possible to get CVS to do this, but an early attempt by Pat Nolan was unsuccessful.
We moved on to look at documentation for certain classes. Most of the remaining classes are expected to go away altogether or to be substantially rewritten. The point was raised that it is worthwhile to document even such short-lived code (and rejoinder that this task has such low relative priority that it never gets done in practice). We looked first at TkrClusterAlg. The internal (non-Doxygen) method header comments were not quite what we had expected, likely because we need to do a better job of explaining what the individual fields mean. We saw several Doxygen formatting oddities which should be investigated.
Experiencing our first code documentation review elicited some thoughts on the procedure:
Leon remarked that the process of documenting the code was in itself useful to him.
We (reviewers) could do a better job if the code documentation were available at least 24 hours before the review.
We often found it hard to stick to just discussing the package documentation and not turn the process into something more like a code walk-through. This first review was necessary and useful as a way for us (the DocTF) to gauge whether our requirements on code documentation were sufficient and appropriate, and how good a job we did in describing them. Is there any reason to continue to have code documentation reviews independent of code walk-throughs?
Action Items for Documentation Task Force
Write up Review Report.
Specify format for release.notes, similar or identical to that used in TkrRecon.
Look into automating entries into release.notes (i.e., soliciting and formatting comment) at rtag time.
Clarify meaning of fields in recommended header for implementation file comments on methods.
Investigate various Doxygen quirks (e.g., strange indentation; unnecessarily wide output requiring horizontal scroll bars, ..).
Back to DocTF Home Back to GLAST Software Home
J. Bogart Last Modified: 04-Aug-2004 15:58:17 -0700
