[vtkusers] "State of the documentation address"

[Dave Partyka]

The script that does this magic is in VTK\Utilities\Doxygen\
doc_header2doxygen.pl. From a quick glance at the file it might not be an
easy fix.

On Wed, Nov 18, 2009 at 10:50 AM, David E DeMarle
<dave.demarle at kitware.com>wrote:

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