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.<br>

<br><br><div class="gmail_quote">On Wed, Dec 9, 2009 at 6:07 PM, David Doria <span dir="ltr"><<a href="mailto:daviddoria%2Bvtk@gmail.com">daviddoria+vtk@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">

As an example, in vtkMath.h, there are many functions defined after<br>
the end of the class. Some of these have comments:<br>
<br>
//----------------------------------------------------------------------------<br>
// Cross product of two 3-vectors. Result (a x b) is stored in z[3].<br>
inline void vtkMath::Cross(const float x[3], const float y[3], float z[3])<br>
{<br>
  float Zx = x[1] * y[2] - x[2] * y[1];<br>
  float Zy = x[2] * y[0] - x[0] * y[2];<br>
  float Zz = x[0] * y[1] - x[1] * y[0];<br>
  z[0] = Zx; z[1] = Zy; z[2] = Zz;<br>
}<br>
<br>
and some don't<br>
<br>
//----------------------------------------------------------------------------<br>
inline float vtkMath::RadiansToDegrees()<br>
{<br>
  VTK_LEGACY_REPLACED_BODY(vtkMath::RadiansToDegrees, "VTK 5.4",<br>
                           vtkMath::DegreesFromRadians);<br>
<br>
  return vtkMath::DegreesFromRadians( 1.f );<br>
}<br>
<br>
Should we comment them all with the same comments that were used in<br>
the function declarations for consistency? It seems to have been<br>
arbitrarily decided which functions are "complicated enough" to<br>
warrant a comment. It doesn't look like these are used in the doxygen,<br>
but I think this would improve code readability.<br>
<br>
Thoughts?<br>
<br>
Thanks,<br>
<br>
David<br>
_______________________________________________<br>
Powered by <a href="http://www.kitware.com" target="_blank">www.kitware.com</a><br>
<br>
Visit other Kitware open-source projects at <a href="http://www.kitware.com/opensource/opensource.html" target="_blank">http://www.kitware.com/opensource/opensource.html</a><br>
<br>
Follow this link to subscribe/unsubscribe:<br>
<a href="http://www.vtk.org/mailman/listinfo/vtk-developers" target="_blank">http://www.vtk.org/mailman/listinfo/vtk-developers</a><br>
<br>
</blockquote></div><br><br clear="all"><br>-- <br>William J. Schroeder, PhD<br>Kitware, Inc.<br>28 Corporate Drive<br>Clifton Park, NY 12065<br><a href="mailto:will.schroeder@kitware.com">will.schroeder@kitware.com</a><br>

<a href="http://www.kitware.com">http://www.kitware.com</a><br>(518) 881-4902<br>
<input id="gwProxy" type="hidden"><input onclick="jsCall();" id="jsProxy" type="hidden"><div id="refHTML"></div>