[vtk-developers] holes in documentation

[kent williams]

Haha, yeah.  Well I've done a lot of ITK contributions, and I have
been back and forth with Karthik about the vtkContourWidget, pointing
out some minor bugs.  I don't know if I'm ready/able to start checking
in changes to VTK, since I'm still a noob.   But our current projects
at the University Of Iowa Dept of Psychiatry are based around the
whole Kitware tool chain and Slicer 3, so I'll definitely be pitching
in where I can.

After I went home last night, I realized I'd been venting after some
hours of frustration. I hope I haven't offended, and I promise I won't
be one of those mailing lists cranks who ends up annoying everyone.

On Dec 21, 2007 5:40 AM, Will Schroeder <will.schroeder at kitware.com> wrote:
> 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)