[vtkusers] "State of the documentation address"

[Marcus D. Hanwell]

On Wednesday 18 November 2009 10:27:50 David Doria wrote:
> On Sat, Nov 14, 2009 at 3:20 PM, David Doria <daviddoria+vtk 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??
> 
I care - I spoke to you last week about some issues I had spotted with 
documentation. The bleed through effect of the first doxygen comment - is that 
something that could be fixed in the script that generates the doxygenified 
headers? That would reduce the effect of this issue, and seems to be a common 
assumption in our headers.

If not then I guess we need to add quite a few new documentation comments. I 
will certainly start adding things as I work on code, but didn't want to do 
anything without knowing if this was a broken script or a broken assumption on 
how the doxygen comments work.

Marcus
-- 
Marcus D. Hanwell, Ph.D.
R&D Engineer, Kitware Inc.
(518) 881-4937