[vtk-developers] comments inside BTX ETX + matrix variable naming

[Moreland, Kenneth]

I'm going to dissent with Marcus, Berk, and others on the desirability off verbose documentation and side with David D.  In review, David's proposed changed documentation is as follows.

//BTX
  // Description:
  // Multiplies matrices a and b and stores the result in c according to
  // c = ab. These matrices are specified as vector indicating a matrix in
  // row major order. For example, the matrix
  // [a00 a01 a02]
  // [a10 a11 a12]
  // [a20 a21 a22]
  // should be defined as
  // double a[9] = {a00, a01, a02, a10, a11, a12, a20, a21, a22};
  static void Multiply3x3(const double a[9], const double b[9],
                          double c[9]);
//ETX

I think this is a fine example of documenting a method. (However, David, be aware that the html document will not preserve the line formatting you have here.  You will have to add some tags to ensure that, at a minimum, the matrix example is lain out sensibly.)  The description is clear both in being mathematically non-ambiguous and in being easy for a user to understand.  And the documentation is not that long.  The whole thing is basically three sentences.  I personally really appreciate David taking the time to improve the documentation on some of the most used methods in VTK.

I would not go so far as to say that such detailed documentation should be required on all methods.  Most methods could be sufficiently summed up in 1 or 2 sentences and under 20 words.  But other methods could be made more clear when its operations and conventions are spelled out.  In this case, it is quite helpful to spell out what row order means.  I personally have a hard time associating descriptive means with technical terms.  As I'm using this function, I need to worry about the layout of the memory, possibly indexing into 2D arrays, and of course the operation of the matrix multiply itself.  It is convenient to have a little diagram in the documentation showing me where the matrix entries go in the array.

I also think providing example usage code is perfectly acceptable.  Example code is probably excessive most of the time, but there are some circumstances (for example in the vtkOpenGLExtensionManager documentation) where a small piece of code elucidates a method's or class' usage.  We shouldn't be discouraging designers from using examples in the documentation if it is helpful.

-Ken


On 12/12/09 12:05 PM, "Berk Geveci" <berk.geveci at kitware.com> wrote:

I agree with Marcus, specially in not having to explain what row major order is.

On Sat, Dec 12, 2009 at 10:30 AM, David Cole <david.cole at kitware.com> wrote:
> On Sat, Dec 12, 2009 at 10:23 AM, David Doria <daviddoria+vtk at gmail.com>
> wrote:
>>
>> On Sat, Dec 12, 2009 at 10:17 AM, Francois Bertel
>> <francois.bertel at kitware.com> wrote:
>> > Arguments of functions and methods in VTK start with lowercase. So
>> > it's is not OK. Only the variable member of a class start with an
>> > upper case.
>>
>> It seems very annoying to not comply with mathematics notation, which
>> is clearly more standard than VTK notation.
>>
>
> Sorry it's annoying to you....
>
> But it's not "more standard" with respect to VTK coding conventions. VTK's a
> visualization package with some math stuff in it, not a math package with
> some visualization stuff in it.
>
> :-)
>
>
> _______________________________________________
> Powered by www.kitware.com
>
> Visit other Kitware open-source projects at
> http://www.kitware.com/opensource/opensource.html
>
> Follow this link to subscribe/unsubscribe:
> http://www.vtk.org/mailman/listinfo/vtk-developers
>
>
>
_______________________________________________
Powered by www.kitware.com

Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html

Follow this link to subscribe/unsubscribe:
http://www.vtk.org/mailman/listinfo/vtk-developers





   ****      Kenneth Moreland
    ***      Sandia National Laboratories
***********
*** *** ***  email: kmorel at sandia.gov
**  ***  **  phone: (505) 844-8919
    ***      web:   http://www.cs.unm.edu/~kmorel


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/vtk-developers/attachments/20091214/2ed58738/attachment.html>