[vtkusers] Documentation rules discussion

[David Doria]

I think a discussion about how the documentation should be updated is in order.

Here is the current major problem:

 // Description:
 //  Minimum number of cells per spatial region.  Default is 100.
 vtkSetMacro(MinCells, int);
 vtkGetMacro(MinCells, int);

Results in doxygen pages like:

virtual void vtkKdTree::SetTiming ( int) [virtual]
Turn on timing of the k-d tree build

virtual int vtkKdTree::GetTiming ()     [virtual]
Turn on timing of the k-d tree build

What we don't want is a comment that gives the reader no new information:

 // Description:
 //  Set MinCells
 vtkSetMacro(MinCells, int);

 // Description:
 //  Get MinCells
 vtkGetMacro(MinCells, int);

Is redundancy like the following ok? I think it really should be there
in both places because if you click the GetXX link
(http://www.vtk.org/doc/nightly/html/classvtkKdTree.html#a65b6df1a1306d9b1f7e9d1b5f2ea0c1b)
you don't want to have to go looking for the SetXX description to
figure out what is going on.

 // Description:
 //  Set the minimum number of cells per spatial region. Default is 100.
 vtkSetMacro(MinCells, int);

 // Description:
 //  Get the minimum number of cells per spatial region. Default is 100.
 vtkGetMacro(MinCells, int);

Does the default value belong in either of these places? Shouldn't it
go in the attribute description
(http://www.vtk.org/doc/nightly/html/classvtkKdTree.html#ab7c3b646debb98cad867a0391d281774).
Maybe only attributes that have set/get functions defined should have
a description, and this description should include the default value?

Is there a way to put a link to this attribute description in the
set/get descriptions? Something like:

 // Description:
 //  Set the minimum number of cells per spatial region. See
<MinCells> for more details.
 vtkSetMacro(MinCells, int);

 // Description:
 //  Get the minimum number of cells per spatial region. See
<MinCells> for more details.
 vtkGetMacro(MinCells, int);

Any thoughts on these types of things?

Thanks,

David