Documentation Rules
From KitwarePublic
Jump to navigationJump to search
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.
// 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);
Set/GetVectorMacros
The documentation style for vector macros is to name each of the resulting variables. For example
// Description:
// Set/Get DrawValue. This is the value that is used when filling data
// or drawing lines.
vtkSetVector4Macro(DrawColor, double);
vtkGetVector4Macro(DrawColor, double);
produces in the doxygen:
virtual void SetDrawColor (double, double, double, double)
We must therefore name the variables in the description, like
// 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);
Set/GetMacros + Boolean
There must be a single description for this triple of macros. For example:
// Description:
// Turn on/off the generation of elliptical splats.
vtkSetMacro(NormalWarping,int);
vtkGetMacro(NormalWarping,int);
vtkBooleanMacro(NormalWarping,int);
SetClamp/GetMacros
The description must describe the valid range of values.
// Description:
// Should the data with value 0 be ignored? Valid range (0, 1).
vtkSetClampMacro(IgnoreZero, int, 0, 1);
vtkGetMacro(IgnoreZero, int);