Minutes January 22, 2002
Attendance: Joanne Bogart, Heather Kelly, Traudl Hansl-Kozanecka, Mark Strickman, Karl Young
This was the second meeting of the Documentation Task Force.
ChangeLog
Discussed use of ChangeLog as the place to store the modification history
for all files, classes, and functions. Some desired storing the
modification history directly with the source code. There was some concern
that the ChangeLog would not provide enough detailed information, though code
documentation reviews should help instill the need to provide meaningful log
messages. Currently, the ChangeLog generation is automatic and in addition
it can be edited and checked back into the repository. It was decided that
we would recommend using the ChangeLog to store the modification history.
LaTeX
Regis Terrier had sent in a question concerning the code documentation
recommendations, which we discussed during the meeting:
LaTeX is required for Doxygen processing of mathematical formulae.
Should we provide any information concerning latex download? Is it enough
that the official Doxygen documentation is produced on a system where LaTeX is
available? We agreed that is was enough that LaTeX be available during
official Doxygen production. We should not get into the business of
specifying LaTeX installations on local user's machines. However, we
should provide an example of inserting a mathematical formula into the
Doxygen documentation.
Images and HTML Tags in Implementation Documentation
Regis Terrier had sent in this question concerning the code documentation
recommendations, which we discussed during the meeting:
Within the comment blocks included within the implementation (cxx)
files, it may be desirable to import an image or HTML link to provide supporting
material concerning the physics behind a function. However, our code
recommendations do not allow Doxygen comments within the implementation file -
except where the declaration occurs within an implementation file.
It was generally agreed that the code documentation within the code should be kept "light". Meaning, it may not be desirable to import images - in fact, we will not explicitly provide a recommendation at this time concerning images. As far as HTML links, Mark recommended that gory Physics details could be referred to in a supporting document - preferably one maintained within the standard GLAST documentation library - something under configuration control. We then discussed CyberDocs - and whether this might be the appropriate place for some supporting documentation. Traudl will contact Richard concerning potential SAS usage of CyberDocs. However, as Karl mentioned some detailed documentation could reside within the package's doc directory. It may be that some documentation belongs within CyberDocs and other more code specific documents could reside in the package. We will review this at an upcoming meeting.
$Header$ Keyword
Bob Schaefer has recommended that we store the RCS $Header$ keyword as a
static char* in all files checked into the CVS repository. The main
benefit is that all object files and executables could then be queried to
determine the version of the file used during the compilation. Ultimately,
would this require modifying every file in the repository? Traudl stated
that, no, we did not have to require all files be updated...rather from this
point forward the RCS $Header$ should be stored.. However, the file
versions are not as useful as knowing the package tags. Karl mentioned
that all tags are stored by the release manager when checking out and compiling
code. It was also mentioned that output files should store the version of
the software used to generate it - but that's a discussion for another task
force. We will discuss $Header$ keyword at this week's software core
meeting.
Initial Code Recommendations to be Released
We agreed to release the code recommendations on the unsuspecting SAS
developers today. We now need to plan some code documentation reviews and
spot checks.
Web Recommendations
With the initial draft of the code recommendations finished - we are now
turning our attention to the web recommendations. This will be discussed
in more depth soon. For now, Mark just mentioned the need for some
configuration management - i.e. preventing web pages from just
disappearing. Heather wonders about web organization and minor
web page recommendations such as standard header and footers.
Next Meeting:
Tentatively scheduled for next Tuesday January 29nd at 8:30 AM PST.
Action Items:
Traudl will contact Richard concerning CyberDocs usage.
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.