[vtkusers] "State of the documentation address"

[David Doria]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.vtk.org/pipermail/vtkusers/attachments/20091114/eb4c0f94/attachment.htm>