Programmer's Guide to ``Pan'': Commenting Recommendations

Pan is documented in part through its Class Index, a ``living'' documentation of the code as it exists now, which is updated periodically using the THtml class. It is maintained using CVS. That being the case, it is recommended that Pan programmers supply comments in a form THtml can use to clarify each class, and CVS can use to supply version information. Namely:

• Start each implementation file with a comment block of the following form:

  //**********************************************************************
  //
  //     HALL A C++/ROOT Parity Analyzer  Pan           
  //
  //        TaLabelledQuantity.cc  (implementation)
  //
  // Author:  R. Holmes <http://physics.syr.edu/~rsholmes>, A. Vacheret
  // @(#)pan/src:$Name:  $:$Id: comments.html,v 1.2 2006/08/25 20:35:37 rsholmes Exp $
  //
  ////////////////////////////////////////////////////////////////////////
  //
  //    A class of quantities with associated labels and units.
  //
  ////////////////////////////////////////////////////////////////////////
        

  The // Author: string identifies to THtml the string it should use for the class authors. Don't use // Authors: even if there's more than one! All authors must be on the same line. The URLs within angle brackets after an author's name may be omitted; you can use a mailto: instead of a web site URL. The // @(#) string indentifies the string THtml should use to describe the latest version; it's built up from two CVS keywords, $Name: $ and $Id: comments.html,v 1.2 2006/08/25 20:35:37 rsholmes Exp $, which CVS will expand automatically. The row of forward slashes indicates the start of the comment that describes the class. (Don't use slashes instead of asterisks in the first line.)

  Methods are described using the comment found at the start of the implementation. This descriptive comment must occur starting on the first line after the opening brace ("{") of the function, and ends at the first non-comment line. One quirk seems to be that if the function returns a templated type, the function implementation is not found unless the type is on a separate line. So there are two things wrong with

  vector<pair<ECutType,Int_t> > TaCutList::CutsFailed (const TaEvent& ev) const 
  {
  
    // Return a vector of cuts (pairs of cut type and value) for which
    // the given event is inside an interval.
  ...
  }
  

  -- the templated function type is not on a separate line, and the function description has a blank line before it. Change this to

  vector<pair<ECutType,Int_t> >
  TaCutList::CutsFailed (const TaEvent& ev) const 
  {
    // Return a vector of cuts (pairs of cut type and value) for which
    // the given event is inside an interval.
  ...
  } .
  

  It's the implementation (.cc) file THtml uses, not the header or interface (.hh) file, for class descriptions. Still, it's probably best to cut and paste the start-of-file comment block from the implementation file to the interface file, replacing the appropriate line, e.g.

  //        TaLabelledQuantity.cc  (implementation)
        

  by

  //        TaLabelledQuantity.hh  (interface) .
        

  THtml does, however, look in the interface file (or rather, in the dictionary file which looks in the interface file) for comments describing the data members of each class. You should put a brief description after each data member, on the same line. Declare each data member in a separate statement. E.g.:

    // Data members
    string fName;   // Name of the quantity
    Double_t fVal;  // Value of the quantity
    string fUnits;  // Units for the quantity
  

  There should be a terse class description in a comment after the ClassDef macro:

  #ifdef DICT
    ClassDef(TaCutList, 0)   // List of cuts
  #endif
  

  This is used on the index page after the class name.