[vtk-developers] holes in documentation

[Will Schroeder]

Kent-

Open source software means pitching in when you see problems :-) We all know
that the documentation needs improvement; but given the size of the system
and the velocity of development; it is hard to keep up with it and
volunteers are needed. We are looking forward to your contributions ;-)

W

On 12/20/07, kent williams <nkwmailinglists at gmail.com> wrote:
>
> 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.
> _______________________________________________
> vtk-developers mailing list
> vtk-developers at vtk.org
> http://www.vtk.org/mailman/listinfo/vtk-developers
>



-- 
William J. Schroeder, PhD
Kitware, Inc.
28 Corporate Drive
Clifton Park, NY 12065
will.schroeder at kitware.com
http://www.kitware.com
518-371-3971 (phone and fax)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/vtk-developers/attachments/20071221/993130a9/attachment.html>