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.

  // 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);