[vtk-developers] Documentation Parsing

[David Cole]

I think it would be time better spent to fix the actual problem.

I don't think it's intentional that the script requires a newline preceding
the "// Description" blocks... I can't see from the code why that would be
the case. Guess my perl is rusty.

Is there a brave perl volunteer listening that can save Brian from the
drudgery of adding blank lines here and there...?


On Tue, Apr 5, 2011 at 1:02 PM, Brian Helba <brian.helba at kitware.com> wrote:

> In a number of cases, Utilities/Doxygen/doc_header2doxygen.pl is failing
> to parse and translate "// Description:" blocks in VTK header files into
> actual Doxygen-style comment blocks. Specifically, 351 function descriptions
> across 101 classes appear to be affected.
>
> The issue can arise when the line "// Description:" is not preceded by a
> newline. The Perl script does check for other documentation tags (//BTX,
> //ETX) and qualifiers (public, etc.) but only correctly parses the very
> first block; subsequent blocks that immediately follow tags, qualifiers, or
> other Description blocks fail to be translated.
>
> The long-term fix is to make Utilities/Doxygen/doc_header2doxygen.pl more
> robust, as it already attempts to correct for non-conforming code in some
> cases. Also, the standards at
> http://www.vtk.org/Wiki/VTK_Coding_Standards#Documentation_Standards do
> not seem to make it adequately clear that a newline should precede all
> declaration blocks that include a "// Description:". If this is the
> standard, it should be clarified; if not, fixing the Perl script would be a
> much higher priority.
>
> Meanwhile, I'm planning to directly fix the affected documentation by
> simply inserting newlines. Should I modify only the places where parsing
> errors actually do occur, or should I add newlines before all "//
> Description:" blocks that don't already have them (to conform with the
> potential standard), even if they are being parsed correctly?
>
> Brian Helba
>
> _______________________________________________
> 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
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/vtk-developers/attachments/20110405/886188ce/attachment.html>