[vtk-developers] inlined function comments

[Will Schroeder]

Personally I do not like to see information duplicated, it has a tendency to
get out of date or become inconsistent. If it's not obvious enough where the
documentation is (declaration) you can always explicitly put "See function
declaration for documentation." or something to that effect.


On Wed, Dec 9, 2009 at 6:07 PM, David Doria
<daviddoria+vtk at gmail.com<daviddoria%2Bvtk at gmail.com>
> wrote:

> As an example, in vtkMath.h, there are many functions defined after
> the end of the class. Some of these have comments:
>
>
> //----------------------------------------------------------------------------
> // Cross product of two 3-vectors. Result (a x b) is stored in z[3].
> inline void vtkMath::Cross(const float x[3], const float y[3], float z[3])
> {
>  float Zx = x[1] * y[2] - x[2] * y[1];
>  float Zy = x[2] * y[0] - x[0] * y[2];
>  float Zz = x[0] * y[1] - x[1] * y[0];
>  z[0] = Zx; z[1] = Zy; z[2] = Zz;
> }
>
> and some don't
>
>
> //----------------------------------------------------------------------------
> inline float vtkMath::RadiansToDegrees()
> {
>  VTK_LEGACY_REPLACED_BODY(vtkMath::RadiansToDegrees, "VTK 5.4",
>                           vtkMath::DegreesFromRadians);
>
>  return vtkMath::DegreesFromRadians( 1.f );
> }
>
> Should we comment them all with the same comments that were used in
> the function declarations for consistency? It seems to have been
> arbitrarily decided which functions are "complicated enough" to
> warrant a comment. It doesn't look like these are used in the doxygen,
> but I think this would improve code readability.
>
> Thoughts?
>
> Thanks,
>
> David
> _______________________________________________
> Powered by www.kitware.com
>
> Visit other Kitware open-source projects at
> http://www.kitware.com/opensource/opensource.html
>
> Follow this link to subscribe/unsubscribe:
> 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) 881-4902
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/vtk-developers/attachments/20091210/413ab4bb/attachment.html>