[vtk-developers] holes in documentation

kent williams nkwmailinglists at gmail.com
Thu Dec 20 16:34:16 EST 2007


I don't have the current VTK book -- I have 3rd Edition, but it seems
to me that there are some rather gaping holes in the documentation for
VTK that I come across.

Here's one example that I've spent a while scratching my head over:

There is a static member function vtkPolygon::PointInPolygon. Great! I
don't have to look that one up, code and debug it!

But, look at the function signature:

int vtkPolygon::PointInPolygon (double x[3], int numPts, double *pts,
                                double bounds[6], double *n)

I think I can assume that the 'pts' parameter points to an array of 3D
points -- i.e. x,y,z,x,y,z,x,y,z etc.  But does it say that anywhere?
I have to infer that from reading the source code.

Furthermore, nowhere does it explain that the parameter 'n' is the
normal of the polygon -- again I found that out by reading the source.

More mysteries: how do I construct a vtkPolygon from a list of points?
Is there any real use for a naked vtkPolygon?

Every example I can find that appears relevant to these questions does
mystifying things with vtkCells without any comments explaining what's
going on. My one best effort of dealing with vtkCell coding directly
was a miserable failure.

Everything to do with vtkCell and descendents is PFM to anyone except
the implementers.  I'm not the brightest programmer in the world but
I've been banging my head on this stuff for quite a while now, and it
seems to me that there could be better Doxygen comments.

And it wouldn't hurt to have better documentation of VTK internals
because, unfortunately, any sort of information hiding seems to fall
apart any time I try and do anything non-trivial. The internals don't
stay internal, either because of gaps in the API, or for lack of any
convenient higher-level interface to leave the book-keeping behind the
curtain.

This may seem like just bellyaching, and maybe it is, but I can't be
the only person who has gotten frustrated trying to understand VTK.
Really, I appreciate all the great things VTK can do for me, and I
only want it to become better, and easier to use.



More information about the vtk-developers mailing list