The script that does this magic is in VTK\Utilities\Doxygen\<a href="http://doc_header2doxygen.pl">doc_header2doxygen.pl</a>. From a quick glance at the file it might not be an easy fix.<div><br><div class="gmail_quote">On Wed, Nov 18, 2009 at 10:50 AM, David E DeMarle <span dir="ltr"><<a href="mailto:dave.demarle@kitware.com">dave.demarle@kitware.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">People certainly care as documentation really is important.<br>
<br>
However even changes to documentation take developer time. The time is<br>
not just the time it takes to edit a file and commit a new version,<br>
but also the time to make sure the new comment is more correct than<br>
the original and the time that it takes to make sure that some errant<br>
typo doesn't break a dashboard. Changes to the doxygen rules<br>
themselves take additional time.<br>
<br>
Developer time either has to be paid for somebody (and that somebody<br>
is likely paying for something other than existing code quality<br>
improvements), or it has to come out of a developer's free time.<br>
<br>
That is why no one volunteered.<br>
<br>
cheers,<br>
<font color="#888888"><br>
David E DeMarle<br>
Kitware, Inc.<br>
R&D Engineer<br>
28 Corporate Drive<br>
Clifton Park, NY 12065-8662<br>
Phone: 518-371-3971 x109<br>
</font><div><div></div><div class="h5"><br>
<br>
<br>
On Wed, Nov 18, 2009 at 10:27 AM, David Doria <<a href="mailto:daviddoria%2Bvtk@gmail.com">daviddoria+vtk@gmail.com</a>> wrote:<br>
> On Sat, Nov 14, 2009 at 3:20 PM, David Doria <<a href="mailto:daviddoria%2Bvtk@gmail.com">daviddoria+vtk@gmail.com</a>> wrote:<br>
>> I had a few minutes so I thought it would be productive to start to make a<br>
>> list of problems in the documentation. I was looking at the current doxygen<br>
>> pages (e.g.<br>
>> <a href="http://www.vtk.org/doc/nightly/html/classvtkLandmarkTransform.html" target="_blank">http://www.vtk.org/doc/nightly/html/classvtkLandmarkTransform.html</a>) I will<br>
>> maintain the list here:<br>
>> <a href="http://www.vtk.org/Wiki/VTK#Documentation_Improvement" target="_blank">http://www.vtk.org/Wiki/VTK#Documentation_Improvement</a><br>
>><br>
>> After not very long, I realized that this was not such a productive exercise<br>
>> (see below). We really need to just go through class by class and make sure<br>
>> every function has at least a brief/correct description for now (and that<br>
>> the doxygen syntax is correct). We can go back and fill in the real<br>
>> meat/good descriptions slowly.<br>
>><br>
>> Here is what I came up with after only going through 3 classes...<br>
>><br>
>> ===vtkMath===<br>
>> * Pi, DoubleTwoPi, DoublePi all just say "useful constants. Maybe they could<br>
>> say something like "2 * 3.14159..." or 2 *\pi or something like that?<br>
>> * DegreesFromRadians says "Useful constants". This is incorrect. It should<br>
>> explain the conversion along with specify if there are/aren't bound on the<br>
>> input.<br>
>> * DoubleDegreesToRadians says "useful constants". This is incorrect.<br>
>> * DoubleRadiansToDegrees says "useful constants". This is incorrect.<br>
>> * Round(double) says "useful constants". This is incorrect.<br>
>> * Floor() has no documentation at all.<br>
>> * Outer(double, double, double) says "useful constants". This is incorrect.<br>
>> * Norm(double, int) says "useful constants". This is incorrect.<br>
>> * Perpendiculars(double, double, double, double) says "useful constants".<br>
>> This is incorrect. x,y,z, and theta must be explained.<br>
>> * Outer2D says "useful constants". This is incorrect.<br>
>> * Determinant2x2(double, double) says "Useful constants". This is incorrect.<br>
>> * LUFactor3x3(double, int) says "useful constants". This is incorrect.<br>
>> * LUSolve3x3(double, int,double) says "useful constants". This is incorrect.<br>
>> * LinearSolve3x3(double,double,double) says "useful constants". This is<br>
>> incorrect.<br>
>> The list goes on....<br>
>><br>
>> ===vtkKdTree===<br>
>> * TimingOff() says "turn ON timing"<br>
>> * SetTiming(int) says "turn on timing". It should say "turn on timing and<br>
>> set the interval (of what?) to the input X (the input variable is not named<br>
>> - also a problem).<br>
>> * GetTiming says "turn on timing". This is incorrect.<br>
>> * GetMinCells() says "turn on timing". This is incorrect.<br>
>> * SetNumberOfRegionsOrLess has no documentation.<br>
>> * SetNumberOfRegionsOrMore has no documentation.<br>
>> * SetFudgeFactor has no documentation.<br>
>> * RemoveDataSet says "Turn on timing". This is incorrect.<br>
>> * PrintVerboseTree says "Turn on timing"<br>
>> * All CreateCellLists functions have no documentation.<br>
>> * GetIncludeRegionBoundaryCells/On/Off say "turn on timing". This is<br>
>> incorrect.<br>
>> * GetCellLists functions say "turn on timing". This is incorrect.<br>
>> * GetRegionContainingCell says "turn on timing". This is incorrect.<br>
>> * BuildLocatorFromPoints(vtkPoints) says "turn on timing". This is<br>
>> incorrect.<br>
>> The list goes on...<br>
>><br>
>> ===vtkLandmarkTransform===<br>
>> * SetTargetLandmarks/SetSourceLandmarks - both of these have the same<br>
>> description. One should talk about the target only and the other should talk<br>
>> about the source only.<br>
>> * GetSource/TargetLandmarks - same description as the Set* methods. This is<br>
>> incorrect.<br>
>> * SetModeToRigidBody has the same desciption as SetSourceLandmarks. This is<br>
>> incorrect.<br>
>> * SetModeTo* has the same description as SetSourceLandmarks. This is<br>
>> incorrect.<br>
>> * GetMTime - says "Get the MTime". What is MTime? Modification time? Maybe<br>
>> "Get the time at which the object was last modified."<br>
>><br>
>> How can we start to divide/assign the work? This is what I would consider a<br>
>> lucky and unusual case - a HUGE problem with a VERY easy solution.<br>
>><br>
>> Thanks,<br>
>><br>
>> David<br>
>><br>
><br>
> I was expecting a lot of "wow that is shocking!!" type responses - I<br>
> guess no one cares??<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>
> Please keep messages on-topic and check the VTK FAQ at: <a href="http://www.vtk.org/Wiki/VTK_FAQ" target="_blank">http://www.vtk.org/Wiki/VTK_FAQ</a><br>
><br>
> Follow this link to subscribe/unsubscribe:<br>
> <a href="http://www.vtk.org/mailman/listinfo/vtkusers" target="_blank">http://www.vtk.org/mailman/listinfo/vtkusers</a><br>
><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>
Please keep messages on-topic and check the VTK FAQ at: <a href="http://www.vtk.org/Wiki/VTK_FAQ" target="_blank">http://www.vtk.org/Wiki/VTK_FAQ</a><br>
<br>
Follow this link to subscribe/unsubscribe:<br>
<a href="http://www.vtk.org/mailman/listinfo/vtkusers" target="_blank">http://www.vtk.org/mailman/listinfo/vtkusers</a><br>
</div></div></blockquote></div><br></div>