[vtkusers] "State of the documentation address"

[David E DeMarle]

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> 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??
>
> 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
>