[Insight-developers] Documentation changes and rules...

[Will Schroeder]

Hi Folks-

After talking to Jim Miller, and based on the feedback from the list (none), we have a adopted a final documentation style. Here are the rules.

1) Always use /** */ style. A single line comment should be:

/** A single line comment. */

It should be a grammatically correct sentence with a period.

A multiline comment will be:

/** This is a multiline comment.
 *  The comment continues. */

The point is to minimize the white space. The previous .h files were too hard to visually parse and way too long. Please use the English language, grammatically correct. Add enough documentation so that even your educated mother could get an idea of what the class does. If you do something like: "This class implements the algorithm of Yoo and Me, see reference blah." make sure that you also summarize the code, with an indication of how to use it and why it is useful. Please don't be lazy and leave it to a paper to explain what you did.


2) Groups are delimited by blank lines. There are three groups below.

  /** Standard class typedefs.
  typedef Mesh                Self;
  typedef PointSet<TPixelType, VDimension, TMeshTraits>  Superclass;
  typedef SmartPointer<Self>  Pointer;
  typedef SmartPointer<const Self>  ConstPointer;

  /** Hold on to the type information specified by the template parameters. */
  typedef TMeshTraits   MeshTraits;
  typedef typename MeshTraits::PixelType                PixelType;  
  typedef typename MeshTraits::CellPixelType            CellPixelType;  

  /** Set/Get foo parameter controlling the convergence of the algorithm.
   * This is an important paramter that must be specified. */
  itkSetMacro(Foo,int);
  itkGetMacro(Foo,int);

Groups are encouraged because they save so much space. The documentation will be applied to each group of code. (Note: we are achieving this by running a PERL script on the .h file to put in the Doxygen //@{ and //@} grouping symbols....you don't use them, just use blank lines.)


3) Groups should not be mixed. Doxygen does not like groups with enums and typedefs, for example. Separate them out.


4) If you want a brief line (recommended only for class documentation), you must put an explicit \brief Doxygen command in.


That's it, even I can remember these rules, so I'm sure you can too :-)

I've gone through a couple hundred .h files in Common/ IO/ and /Numerics to unify the comment style, and will be checking them in momentarily. I will check in the BasicFilters/ and Algorithms/ .h files on Monday (if all goes well). Please let me know if there are any problems.

Will