Minutes March 12, 2002
Attendees: Joanne Bogart, Heather Kelly, Alex Schlessinger, Mark Strickman, Karl Young
Due to the unfortunate time of our meeting, 9:30 AM PST - we were without any of our European colleagues.. The VRVS rooms were full during our regular 8:30 AM PST timeslot. However, we now have our meetings scheduled on VRVS through May.
TkrRecon Review Wrap-up
The review report has been passed onto the viewing public. Leon has read the report and provided some additional comments:
indentation issue - VC++'s format command does not handle enumerations gracefully.
Ultimately it is up to the package owner to be sure that indentation is consistent.
#define FILENAME_H versus __FILENAME_H
we prefer FILENAME_H without any preceding underscores.
As noted in the review report, the DocTF was to look into polishing the Doxygen output. It is possible to provide a customized style-sheet to doxygen during processing. However, this will not have any impact on processing source files. Doxygen encloses source file contents within HTML tags <pre> </pre> which means preformatted. Thus it is up to the developers to conform to the 80 character line width limit as specified in the GLAST SAS Coding Standards. The templates package has been updated.
The Code Documentation Recommendations document has been updated according to the action items specified in the TkrRecon review report. The master Word document has been removed. Now there are three distinct documents: Code Documentation, Web, and Guides.
Karl is studying mechanisms to handle the images stored in the doc/images directory. Recall that during the review, the link to the TkrRecon diagram was broken. When running the Doxygen scripts at SLAC, the output is copied into a web accessible location. Image files should be copied as well - but currently only those files residing in the doxy-html directory are copied. What to do? Karl is wondering about creating a doxy-html/images directory to copy all doc/images files into. However, we want the same behavior on Windows. Karl will consider the situation further, and we will discuss this more at the next meeting.
A potential schedule of code reviews was revealed. The next victim will be G4Generator. After that, the rest of the schedule is subject to modification. We will inform the G4Generator package owners and arrange a date and time for the review.
Given the large number of code reviews planned, it seems unlikely that just the DocTF members can handle the workload. In addition, there will be many packages where one or more DocTF members are actually package owners. The pool of reviewers will be extended so that volunteers from within the core software group can participate. Clearly, those who have already been reviewed, would be the first asked to act as reviewers. Leon and Tracy will be contacted to participate in the upcoming reviews.
During the TkrRecon review, we saw that the documentation review inevitably morphed into a code review. We would like to encourage this in upcoming reviews. However, as Joanne pointed out, we need to be sure we are clear on just what it is that we are reviewing and developers need to be sufficiently aware of what standards they must conform to. There was no good answer forthcoming...Heather will ponder this further...
Web Review
Karl reported that Janani is doing a good job of going through the Code How-To pages. She has pointed out that the path through the pages is non-linear and has offered some good suggestions. A document will be available for the next meeting.
Joanne reported that she has begun looking at the SAS home page. She has started on a document providing an outline of improvements, including providing a hierarchial structure. The document will be made available soon.
Between now and the next DocTF meeting, the group that agreed to work on web issues: Karl, Joanne, Mark, and Heather will communicate offline to see how to proceed.
Action Items
Karl will further ponder how to handle the images during Doxygen processing.
Heather will contact the G4Generator package owners to inform them of their impending code review.
Heather will consider further just what we will be reviewing in these code reviews...
Karl and Janani will finish up their document proposing changes to the organization of the How-To pages.
Joanne will polish up her document concerning the SAS home page organization.
H. Kelly Last Modified: 2010-06-01 15:45:24 -0700