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

[Marcus D. Hanwell]

On Monday 14 December 2009 14:28:38 Moreland, Kenneth wrote:
> 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 don't think we disagree that much. My main point in this case was that the 
row major explanation would be better made *once* (if at all) in the main 
class description, as several methods are affected by this ordering. Also that 
the explanation should be kept reasonably brief, with possibly a link to an 
article explaining this further. This is the standard ordering for C++, so 
there is an argument that it is not strictly necessary but I think this is 
probably a judgment call.

If you define a matrix as double a[3][3] it will also have the correct order, 
and you can pass in *a as the argument to this function for example. This is 
consistent across the class, and so it seemed most appropriate to explain this 
once in the main class summary.
> 
> 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 would prefer to see a global concept such as this placed in the class 
summary, as all methods are affected by the ordering. Ideally C++ objects 
would be used, and it should probably also be pointed out that these methods 
are provided for performance reasons.
> 
> 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.

I totally agree, and am hoping to add some more inline code examples. I think 
the Qt docs demonstrate how useful inline code examples in the API docs can 
be, when used in the right spots. I.e. not for every function but the ones 
where it makes sense. Fuller examples can of course be provided as examples.

I think this could really help ease people into VTK development, and also 
welcome David's efforts in this regard. I was just stating my own feelings on 
how these classes should be documented. I am quite a new Kitware employee, and 
quite new to VTK - many of my opinions arose from work I have done in the Qt 
and KDE development communities.

Marcus

> 
> 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.
> >
> > :-)
> >