[vtkusers] Find closest point on Mesh B from a point on Mesh A. - with off topic comments

[David Doria]

Hi Jim,

I tried to encourage everyone to help clean up the documentation a
while ago and received exactly zero response:
http://vtk.org/Wiki/Documentation_Improvement

There is a current ITK effort to allow users to edit the comments
directly through the http interface to the Doxygen. This will allow
the above to be "crowdsourced" much more easily. Hopefully VTK follows
suit in this effort.

My replies to many of your comments inline below.

> 1. Could the vtkNotUsed() macro could manifest its use in the class
> documentation? Especially since the sole purpose of the macro is to mask out
> the unreferenced parameter warnings.

Can you give a concrete example of a function where you would like to
see this in the Doxygen?

> 2. Could the documentation expose nested functions where they are key to the
> operation? In this case it appears that each of the implementers of
> FindClosestPoint I looked at did a nested call to EvaluatePosition() with
> many of the same parameters, including subid as an update-able reference,
> and in some cases that is where the subid is unused.

As far as I know, no. I think this would get real messy very quickly anyway.

> My basic approach is to
> research the doc and programs to find answers. My last count showed 2293
> classes in the vtk class hierarchy. 292 direct decendents from vtkObject, 3
> from vtkCommand, 19 from vtkInformationKey, 491 classes outside the
> vtkObjectBase group with 346 at the same level as vtkObjectBase. My personal
> feeling is many programmers feel they have a mastery of vtk with maybe up to
> 100 classes directly used.

I don't understand your point here? There is no need for any one
person to master all 2300 classes as long as there is at least one
person (who follows the mailing list!) that is an expert in each of
them.

> There are seventeen pre-built interaction styles, yet everyone seems to
> think they need to create a subclass of vtkInteractorStyleUser or a
> modification of vtkInteractorStyleTrackballCamera to meet their needs.
> VtkInteractorStyleSwitch provides keystroke toggles between Camera, Actor,
> and Joystick and Trackball (C, A, J and T respectively).

I think the reason for subclassing the interactor styles is that it is
usually the most convenient place to handle keypress and mouse events:
http://www.vtk.org/Wiki/VTK/Examples/Cxx/Interaction/KeypressEvents
http://www.vtk.org/Wiki/VTK/Examples/Cxx/Interaction/MouseEvents

> I feel the Doxygen tool generates documentation with a reasonable level of
> interconnection and linkage, I do think there may be some benefit in
> exploring options regarding the specific function and class content in the
> generated doc. That a careful incorporation of some content from the .cxx
> files may reduce the question volume on the user list.

I think Doxygen only looks at header files. The headers should
completely explain the interface, which is all the user should need.
Many of the comments in the headers which get turned into Doxygen can
definitely be improved, but I don't think this requires any
fundamental change, just better comments :)

David