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

[Jim Peterson]

David,
Not a problem.
Let me try to fill this in a bit:

David Doria wrote:
>   
>> 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?
>
>   
Lets take EvaluateLocation() as an example. This function id documented 
(as are most functions) in the virtual definition in vtkCell.h:

  // Description:
  // Determine global coordinate (x[3]) from subId and parametric 
coordinates.
  // Also returns interpolation weights. (The number of weights is equal to
  // the number of points in the cell.)
  virtual void EvaluateLocation(int& subId, double pcoords[3],
                                double x[3], double *weights) = 0;

The vtkQuadraticPyramid.cxx implementation appears to use the subId 
parameter, but only to pass it to the vtkPyramid instance:

//----------------------------------------------------------------------------
int vtkQuadraticPyramid::CellBoundary(int subId, double pcoords[3],
                                      vtkIdList *pts)
{
  return this->Pyramid->CellBoundary(subId, pcoords, pts);
}

The vtkPyramid.cxx implementation says it does not use the subId parm 
via the vtkNotUsed macro:

//----------------------------------------------------------------------------
// Returns the closest face to the point specified. Closeness is measured
// parametrically.
int vtkPyramid::CellBoundary(int vtkNotUsed(subId), double pcoords[3],
                           vtkIdList *pts)
{
...
}

The class documentation for vtkPyramid::CellBoundary is identical to 
vtkQuadraticPyramid:CellBoundary, both refer to vtkCell documentation, 
and neither has any indication whether subId is used or not. More 
importantly, when subId is used in vtkTriangleStrip.cxx or 
vtkPolyLine.cxx, the problem of what it represents is left to the 
programmer.

I realize this would be an ongoing process, but in my opinion, function 
parameters need to be documented and by name. what subId is used for in 
each case needs to be explicit. we should not expect documentation 
readers to have to infer that the pcoords parameter is the parametric 
coordinates described in the documentation.
>> 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
>
>   
your examples are exactly my point. why do a language dependent hack 
when we have observer functions of:

  LeftButtonPressEvent,
  LeftButtonReleaseEvent,
  MiddleButtonPressEvent,
  MiddleButtonReleaseEvent,
  RightButtonPressEvent,
  RightButtonReleaseEvent,
  KeyPressEvent,
  KeyReleaseEvent,
  CharEvent,
  MouseMoveEvent,
  MouseWheelForwardEvent,
  MouseWheelBackwardEvent,

Wouldn't the language independent vtk centric solution make use of these 
observer events instead of the C++ only subclass approach?
>> 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 :)
>   
Unfortunately, the header file is rarely the thing being edited when a 
documentation significant code change is made. In my opinion again, the 
header file describes the interface to the compiler. The implementation 
logic documents the function to the programmer.

Jim