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

[Jim Peterson]

David Doria wrote:
>
> Jim, according to my notes here:
> http://www.vtk.org/Wiki/VTK/Examples/Cxx/PolyData/CellLocator
>
>
>   int subId; //this is rarely used (in triangle strips only, I believe)
>
> If someone can elaborate/make this more accurate that would be great.
>
>   
David,
I chased into the FindClosestPoint function of a few of the 34 
subclasses that implement it (in vtk 5.6). Maybe we should replicate 
this to the developers wish list. I am not sure what the inputs are to 
Doxygen, but it sure would be nice if a couple aspects of this logic 
could be exposed in the documentation:

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.

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.

3. Could we clarify the meaning or context of "Thread Safe Use" 
comments? My honest read at this point is, like the generic cell 
parameter, this is a pre-allocated work variable to avoid local variable 
allocation for presumably performance reasons. This kind of variable use 
is a significant thread safety issue, each thread that uses 
vtkCell::FindClosestPoint() should have its own set of reference variables.

Understand I am not complaining or criticizing, I find myself answering 
more questions on this list than I probably should. 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.
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 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 hope these comments are taken as constructive and possibly help in 
applying limited resources to the best benefit for the community.
Jim