[Insight-developers] Documentation style changes...

[Will Schroeder]

Hi Folks-

I've started reworking the doxygen documentation in the .h files. My major 
objective was to remove the inordinate amount of white space, to get the 
grouping mechanism working properly, and to find a simple style that is 
easy for all of us to remember. Here's what I've come up with. (See 
itkMesh.h or itkImage.h to see what it looks like.)

1. Use the /** comment */ exclusively, and eliminate the extra lines. A 
single line comment looks like:

/** This is single line documentation. */

and a multiline comment looks like

/** This is long
  *  multiline documentation. */

2. Use grouping commands when the documentation applies to many things. For 
example, I'd like to group the standard Self, Superclass, etc. typedefs as 
follows.

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

Of course, there are many other groups that may exist as well and grouping 
should be used to remove whitespace whenever possible.

3. Use the \par <label> command for long descriptions (for example, 
documenting itkMesh). If you do

\par Overview
dfijidfvjifjv
odfkvofkv
\par
sdflvpodkfv
podkfvofkv
\par Usage
difiofjv
dokfvopfkv
\par
dokfvofv
pofvlof
\par References
idvijfv

You would get three blocks of documentation in the class description: 
Overview, Usage, and References. Note that paragraphs within a block (e.g., 
Overview) are delimited with \par with no following label. This properly 
indents and groups the documentation.

(Note: I had to set the doxygen.config flag DISTRIBUTE_GROUP_DOC  = YES to 
get this to work right. It has been cvs commited)

Comments:
+ I really don't like the /// or //! one-line versions. The problem is that 
it causes these one-line comments to be placed all over the doxygen 
documentation (e.g., Public Types) which makes it harder to see a summary 
of what's going on. I suggest that we not use these, and use \brief 
explicitly (like in the class documentation) if we really want the one line 
comments.

+ The grouping style is /*@{  //@}. You may ask, why not //@{  //@}? 
(Doxygen group delimiters are @{ and @}.) This is because the //@{ is 
interpreted as a one-line comment and these one-lines really disrupt the 
layout of the documentation as I mentioned before. Also, the group could be 
terminated with a /*@}*/ but I'm trying to minimize the amount of 
characters, I hate C-style comments, and having to end with */ is a mistake 
waiting to happen.

+ Personally, I think doxygen's commenting style bites. Another alternative 
is to create our own style, and run Perl scripts to convert it into Doxygen 
format, and then run Doxygen. Here's an example

// Brief: a one-liner for classes

// Section: <Name of Section>
// documentation for
// a section. Blank lines would separate paragraphs
//
// a paragraph within the section
// Section: <name>
// another section

// Documentation: for methods, enums, typedefs, data members, etc.
// (as many lines as you like ended by blank line or no more //
// Groups would be naturally organized by blank lines.
typedef a b;
typedef b c;
typedef c d;

// Documentation: this is a one line doc.
void foo(int bar);

My concern is how this might impact the current use of Doxygen, including 
LaTeX usage, etc.

I'd like to hear feedback on this so I can start cleaning up the code.

Thanks,
Will