[vtk-developers] Strange problem with doxygen script

[Marcus D. Hanwell]

On Thursday 10 December 2009 19:34:26 David Doria wrote:
> On Thu, Dec 10, 2009 at 6:42 PM, Francois Bertel
> 
> <francois.bertel at kitware.com> wrote:
> > Marcus thinks it's a bug in the perl script:
> > http://www.vtk.org/pipermail/vtk-developers/2009-November/006466.html
> >
> > On Thu, Dec 10, 2009 at 6:36 PM, David Doria <daviddoria+vtk at gmail.com> 
wrote:
> >> I thought the issue was that the script applied the last available
> >> description to all functions until the next description was stated.
> >> However, this does not seem to be exactly the case.
> >>
> >> For instance, take these RemoveDataSet functions from vtkKdTree.h.
> >> They appear in a block:
> >>
> >>  // Description:
> >>  // Remove the given data set.
> >>  virtual void RemoveDataSet(int index);
> >>  virtual void RemoveDataSet(vtkDataSet *set);
> >>  virtual void RemoveAllDataSets();
> >>
> >> I thought "Remove the given data set" would be applied as the
> >> documentation for each of these 3 functions. However, as you can see
> >> at
> >> http://www.vtk.org/doc/nightly/html/classvtkKdTree.html#ae9d148ce897ac39
> >>bc71809ddcf3b70d7
> >>
> >> "Turn on timing of the k-d tree build" is the documentation for the
> >> second two functions.
> >>
> >> Anyone know why this might be / how to fix it?
> >>
> 
> Ah, I didn't understand that it was the first // Description that
> appears in the header that got applied to all functions with no
> //Description because there are other functions that appear with
> documentation before the "first" function on the actual doxygen page,
> presumably because the //Description is in a superclass?
> 
> Marcus mentioned his perl is a little rusty, are there any perl
> experts in the group who could help with this?
> 
I had another look at this, what the Perl does to the headers and what Doxygen 
actually processes. As far as I can tell this is actually a bug in Doxygen. 
This fall through technique certainly used to work, as can be seen in the old 
VTK 5.2 docs. 

It looks like we are falling afoul of DISTRIBUTE_GROUP_DOC which causes the 
first comment of a group to be reused for all other members of the group. For 
some reason this no longer works, although from what I can tell we are using 
it correctly. From the doxygen docs,

*--
If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC 
tag is set to YES, then doxygen will reuse the documentation of the first 
member in the group (if any) for the other members of the group. By default 
all members of a group must be documented explicitly.
--*

From vtkMatrix3x3 after being transformed by the Perl script,

//@{
  /*! Multiply a homogeneous coordinate by this matrix, i.e. out = A*in.
      The in[3] and out[3] can be the same array. */
  void MultiplyPoint(const float in[3], float out[3])
    {vtkMatrix3x3::MultiplyPoint(*this->Element,in,out); }
  void MultiplyPoint(const double in[3], double out[3])
    {vtkMatrix3x3::MultiplyPoint(*this->Element,in,out); }
  //@}

This incorrectly grabs the comment from the *first group*, not the preceding 
comment in *that group*. I wonder if the fix to this bug,

https://bugzilla.gnome.org/show_bug.cgi?id=312655

is what led to the bug we are hitting here. I have constructed a minimal 
example which seems to reproduce this issue for me using doxygen 1.6.1. I have 
created a new bug report,

https://bugzilla.gnome.org/show_bug.cgi?id=604412

I will see what the response from the author is. If anyone has any further 
ideas please let me know. It would be good to document how the scripts are 
supposed to work. If there any plan to ever just run the header converter on 
the headers one day and do a very big commit so that this Perl step is not 
necessary?

Marcus
-- 
Marcus D. Hanwell, Ph.D.
R&D Engineer, Kitware Inc.
(518) 881-4937