[vtk-developers] Strange problem with doxygen script

[David Doria]

On Fri, Dec 11, 2009 at 6:52 PM, Marcus D. Hanwell
<marcus.hanwell at kitware.com> wrote:
> 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,

I don't know if you were auto-notified of this, but someone responded
that the bug was previously reported:
https://bugzilla.gnome.org/show_bug.cgi?id=593040

It's discouraging that it is 4 months old! :(

Thanks,

David