[vtkusers] "State of the documentation address"

[Lars Matthäus]

Just the other way around - I guess everybody already knows and suffers
(with me) in silence ... But I, too, would greatly appreciate any
improvement in the documentation.

Lars

> I was expecting a lot of "wow that is shocking!!" type responses - I
> guess no one cares??
>
> Thanks,
>
> David

David Doria schrieb:
> 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