Documentation Rules
From KitwarePublic
Contents |
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);
