Kent-<br><br>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 ;-)

<br><br>W<br><br><div><span class="gmail_quote">On 12/20/07, <b class="gmail_sendername">kent williams</b> <<a href="mailto:nkwmailinglists@gmail.com">nkwmailinglists@gmail.com</a>> wrote:</span><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">

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:

<br><br>There is a static member function vtkPolygon::PointInPolygon. Great! I<br>don't have to look that one up, code and debug it!<br><br>But, look at the function signature:<br><br>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?

<br>Is there any real use for a naked vtkPolygon?<br><br>Every example I can find that appears relevant to these questions does<br>mystifying things with vtkCells without any comments explaining what's<br>going on. My one best effort of dealing with vtkCell coding directly

<br>was a miserable failure.<br><br>Everything to do with vtkCell and descendents is PFM to anyone except<br>the implementers.  I'm not the brightest programmer in the world but<br>I've been banging my head on this stuff for quite a while now, and it

<br>seems to me that there could be better Doxygen comments.<br><br>And it wouldn't hurt to have better documentation of VTK internals<br>because, unfortunately, any sort of information hiding seems to fall<br>apart any time I try and do anything non-trivial. The internals don't

<br>stay internal, either because of gaps in the API, or for lack of any<br>convenient higher-level interface to leave the book-keeping behind the<br>curtain.<br><br>This may seem like just bellyaching, and maybe it is, but I can't be

<br>the only person who has gotten frustrated trying to understand VTK.<br>Really, I appreciate all the great things VTK can do for me, and I<br>only want it to become better, and easier to use.<br>_______________________________________________

<br>vtk-developers mailing list<br><a href="mailto:vtk-developers@vtk.org">vtk-developers@vtk.org</a><br><a href="http://www.vtk.org/mailman/listinfo/vtk-developers">http://www.vtk.org/mailman/listinfo/vtk-developers</a><br>

</blockquote></div><br><br clear="all"><br>-- <br>William J. Schroeder, PhD<br>Kitware, Inc.<br>28 Corporate Drive<br>Clifton Park, NY 12065<br><a href="mailto:will.schroeder@kitware.com">will.schroeder@kitware.com</a><br>

<a href="http://www.kitware.com">http://www.kitware.com</a><br>518-371-3971 (phone and fax)