Documentation Rules

Remaining questions

• Where do default values go (with the set/get functions or with the variable definition?)

Standard Set/GetMacros

The documentation style for this type of pair is very straight forward. There MUST be a single //Description for the pair and a brief description of the variable that is being set/get. <source lang="cpp">

 // Description:
 // Set / get the sharpness of decay of the splats. This is the
 // exponent constant in the Gaussian equation. Normally this is
 // a negative value.
 vtkSetMacro(ExponentFactor,double);
 vtkGetMacro(ExponentFactor,double);

</source>

Set/GetVectorMacros

The documentation style for vector macros is to name each of the resulting variables. For example <source lang="cpp">

 // Description:
 // Set/Get DrawValue.  This is the value that is used when filling data
 // or drawing lines.
 vtkSetVector4Macro(DrawColor, double);
 vtkGetVector4Macro(DrawColor, double);

</source>

produces in the doxygen:

<source lang="cpp"> virtual void SetDrawColor (double, double, double, double) </source>

We must therefore name the variables in the description, like <source lang="cpp">

 // Description:
 // Set/Get the color which is used to draw shapes in the image. The parameters are SetDrawColor(red, green, blue, alpha)
 vtkSetVector4Macro(DrawColor, double);
 vtkGetVector4Macro(DrawColor, double);

</source>

Set/GetMacros + Boolean

There must be a single description for this triple of macros. For example: <source lang="cpp">

 // Description:
 // Turn on/off the generation of elliptical splats.
 vtkSetMacro(NormalWarping,int);
 vtkGetMacro(NormalWarping,int);
 vtkBooleanMacro(NormalWarping,int);

</source>

SetClamp/GetMacros

The description must describe the valid range of values. <source lang="cpp">

 // Description:
 // Should the data with value 0 be ignored? Valid range (0, 1).
 vtkSetClampMacro(IgnoreZero, int, 0, 1);
 vtkGetMacro(IgnoreZero, int);

</source>