[vtk-developers] Documentation Parsing

[David Cole]

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

> There won't be much drudgery, I already have a bash/sed script to do the
> necessary edits.


But the edits are unnecessary if the script is fixed....



> It would be nice to get a quick fix in, so the nightly HTML documentation
> is more useful.
>

It has been this way for a long, long time. It would be better to get the
right fix (rather than quick) in and avoid the unnecessary edits.

But maybe that's just me....

Feel free to resolve this however you think is best.



>
> The issue with the script is that not enough analysis is performed within
> each loop iteration to determine where a block of grouped comments /
> function declarations ends. After a "// Description" tag is found at the
> beginning of an iteration, the script expects an arbitrary number of
> comment, code or macro lines. A special case could be added inside the loop:
> while inside a Description block, if another "// Description" tag is
> encountered, end the outer block and continue to another iteration.
>
>
> On Tue, Apr 5, 2011 at 1:18 PM, David Cole <david.cole at kitware.com> wrote:
>
>> 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.plmore 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
>>>
>>>
>>>
>>
>
>
> --
> Brian Helba
> Medical Imaging
> Kitware, Inc.
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.vtk.org/pipermail/vtk-developers/attachments/20110405/d3bda5e7/attachment.htm>