Documentation Improvement

Documentation Improvement!=

Function Parameters

<source lang="cpp"> virtual int IntersectWithLine (double p1[3], double p2[3], double tol, double &t, double x[3], double pcoords[3], int &subId) </source> (taken from vtkAbstractCellLocator's reference page)

Description: "Return intersection point (if any) of finite line with cells contained in cell locator."

Many users first thoughts are: "What is 'tol'? What is 't'? What is 'subId'? What is 'x'? What is 'pcoords'? What are 'p1' and 'p2'? Why does it return an int?"

I recommend having a table like this for every function: (if you see a '?' in the table, that means I'm not sure about this particular cell of the table :) )

Variable	Description	Reasonable value
Return value	1 if the line intersected the polydata, 0 otherwise	n/a
p1 & p2	The end points of the line segment to be intersected with the polydata	n/a
tol	Accounts for floating point precision problems when performing ray/cell intersections	0.01
t	determines ?	?
x	Return the coordinate of the intersection	n/a
subId	Return the index of the cell relative to a triangle strip, if applicable (rarely used)	n/a
pcoords	?	?

Default values

This applies to many, many, classes, but let's take an example.

Can things like this (from the constructor of vtkOBBTree) be listed on the class reference websites? <source lang="cpp">

 this->Level = 4;
 this->MaxLevel = 12;
 this->Automatic = 1;
 this->Tolerance = 0.01;

</source>

A little section like: (again, '?' indicates I'm not sure of the value in this example)

Variable	Description	Default value
Level	I don't even know what this is and I use this class	4
MaxLevel	The depth of the tree?	12
Tolerance	Determines ?	0.01

It seems like it would be extremely informative (instead of going digging through cxx files for this type of information, and often still not finding it).

Virtual Member functions (defined in superclasses)

I will often call a function on a derived class, go to look for it, and find that it is not there! Of course the answer is that it lives in a superclass, but there could be users with limited c++ experience that would not know to look there. Could there be some kind of pointer to the superclass function on the

For example, in my code I often do this: <source lang="cpp"> vtkPolyData* polydata = vtkPolyData::New(); vtkPoints* points3D = vtkPoints::New(); // ... fill points3D .... polydata->SetPoints(points3d); </source lang="cpp">

However, if I go here: http://www.vtk.org/doc/nightly/html/classvtkPolyData.html and search for "setpoints", there is nothing!

Of course going up the hierarchy to: http://www.vtk.org/doc/nightly/html/classvtkPointSet.html will find you what you're looking for, but often you have to go up 3 or 4 levels and by that time it can get very confusing.

On the PolyData page, could there be <source lang="cpp"> virtual void SetPoints (vtkPoints *) (see vtkPointSet) </source>

or something like that? Maybe this is not supported by the dogygen framework?

Action

I think it would take someone with some knowledge of the class less than 10 minutes to go through and make these type of statements, and it would IMMENSELY improve usability for new (and all) users.

Thoughts/comments? If I am the only one that finds this a bit annoying, then fine. But if others agree with me, maybe I can start some sort of wiki "sign up" page with a list of the classes and who will improve the documentation pages? With a group effort I don't think it would take long at all to clean up.