[vtkusers] Improving Documentation

[David Doria]

*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?
  this->Level = 4;
  this->MaxLevel = 12;
  this->Automatic = 1;
  this->Tolerance = 0.01;

A little section like:

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 how close XX are ? | 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).

*Function Paramters*

virtual int IntersectWithLine<http://www.vtk.org/doc/nightly/html/classvtkAbstractCellLocator.html#a7e5ac7a85bd424f78bc8e93c5c4c49a>(double
p1[3], double p2[3], double tol, double &t, double x[3], double
pcoords[3], int &subId)
(taken from vtkAbstractCellLocator's reference page)

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

Here's what I claim is missing: What is tol? What is t? What is subId? What
is x? What is pcoords? And for that matter, what are p1 and p2 (when I first
started using vtk I was expecting to pass a vtkLine object, not 2 points
defining a line segment.)

Even after digging around for quite a while I can't find some of these
answers - and I thought they would have been right on the class reference
page.

*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:
vtkPolyData* polydata = vtkPolyData::New();
vtkPoints* points3D = vtkPoints::New();
// ... fill points3D ....
polydata->SetPoints(points3d);

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
virtual void SetPoints<http://www.vtk.org/doc/nightly/html/classvtkPointSet.html#4842907707c212909aed03195674b498>(
vtkPoints <http://www.vtk.org/doc/nightly/html/classvtkPoints.html> *) (see
vtkPointSet)

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.

Thanks,

David
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.vtk.org/pipermail/vtkusers/attachments/20090811/dd2cf679/attachment.htm>