Minutes January 15, 2002
Attendance: Joanne Bogart, Heather Kelly, Alex Schlessinger, Mark Strickman, Karl Young
This was the first meeting of the Documentation Task Force.
What is the breadth of our charge? Do we cover the Science
Support Center's (SSC) software documentation efforts?
This topic was originally brought up by Mark. The SSC will be
collaborating with the LAT team on science analysis software. The SSC will
be the point of contact for Guest Investigators who will be interested in
tutorials and cookbooks. It seems to just make good sense that we have a
common set of documentation recommendations. We will pursue acquiring a
representative of the SSC to join us in our discussions.
Code Documentation Goals
We discussed the need to more clearly state the purpose of the comments in
the code. We discussed the difference between the purpose of the Doxygen
comments located in the header files and the standard C++ comments inserted
primarily in the implementation file. Doxygen comments are meant to provide a good overview for users,
providing an understanding of the code structure. The goals of inline comments
1) Allow maintenance of code by people not involved in its development; 2) Allow understanding of techniques, algorithms,
requirements, etc when reviewing code. Coders should check their comments against these goals on a regular basis. So should the "doc cop".
Templates for inline documentation, such as listings 1,2,3, in the code
recommendations write up should be more explicit. The template should lead the coder explicitly through
the documentation process and it should make sure that, if the coder fills out each blank, the resulting documentation is what we want.
Something on the order of:
// INPUTS:
// OUTPUTS:
// DESCRIPTION:
Mark agreed to provide an example. Additionally the write up should
include recommendations for the level of detail expected in the comments.
The questions a programmer should make sure their comments address.
Who are the code documentation police?
All agreed that someone much enforce the code documentation
recommendations It would be difficult to automate checking the
documentation. In the end, people must be involved in reading over the
text to be sure it makes sense. This task force will be responsible for
policing - at least in the beginning.
How will code documentation be enforced?
Clearly we do not have the man power to police every update to every
package. Instead, we will rely on code reviews and walkthroughs.
Joanne suggested using spot checks to determine the level of effort that a full
scale documentation review would require. We could also spot check pieces
of packages - rather than every line of code. Do we review every new
version tag of each package? It seems unlikely, but we should have a
better idea once we gain some experience. Reviews will happen more
regularly and be more comprehensive for "important" packages - like
the reconstruction packages. The first such reviews will be the most
tedious, and may consist of walkthroughs. This would share some of the
burden with the package owners. The review results would be communicated to
package owners - what is being done well and what could use some
improvement. We did not discuss how to make sure that package owners
address any documentation issues that arise from the reviews.
release.notes
It has been suggested that the release notes should not just be copied into the
mainpage.h file - rather a link would be preferred. The concern is that as
the release.notes increase in size, they will detract from the contents of the
mainpage file. Heather is concerned about the maintainability of a
link.
Naming of the Doxyfile
It was suggested that we should rename the Doxyfile to something like
doxygen.cfg. It was generally agreed that it is best to continue using the standard name as
specified by the Doxygen user manual.
Protected section in the templates
Toby had suggested that it would be best to remove the protected section
from the code templates. In fact, GLAST SAS should discourage the use of
protected data members. While protected member functions are just fine,
these templates are meant for beginners. More experienced programmers
would presumably know how to add in protected member functions if
necessary. The group agreed to remove the protected examples from the
templates.
JavaDoc versus Qt style Doxygen comments
Traudl had mentioned that she prefers the JavaDoc style of Doxygen comments,
and while we could not enforce its use, it could be recommended. It was
decided to leave it up to the individual programmer. The code
documentation recommendations will mention both possibilities. The code
snippets in the document and the templates will demonstrate the use of the
JavaDoc style.
Editor for our recommendation documents
It was agreed that while the final form will be provided in PDF, while we are
circulating drafts both Word DOC and RTF formats will be provided.
Those who plan to modify the files should notify the group via e-mail before and
after they are finished. Additionally, the release notes at the beginning
of the document should be used to identify who made modifications and a summary
of their changes.
Version of Doxygen
It would be helpful for all users to be aware of what version of Doxygen we
are using. In fact, it might be useful to have a web page denoting the
versions of all tools that are currently sanctioned by the SAS. Karl
agreed to look into that and make it as automated as possible!
Next Meeting:
Tentatively scheduled for next Tuesday January 22nd at 8:30 AM PST.
Action Items:
Alex will confer with Toby about generating an example requirements file for
the templates package.
Mark will provide examples of standard implementation comments and update the code documentation write up to more explicitly provide guidelines for comments.
Heather will finish updating the file, provide new Word Doc and RTF versions on the web site, and inform everyone via e-mail that she is done.
Karl will look into creating a web page that will specify the versions of tools that are in use by the SAS i.e. CMT, ROOT, Doxygen, etc..
Karl will review with Toby the purpose of the settings in the default Doxyfile provided in the GlastPolicy package.
All - finish reviewing the code documentation write-up and polish the templates package. It is hoped these will be officially released by the end of the week.