[vtk-developers] Documentation Parsing

[Brian Helba]

There won't be much drudgery, I already have a bash/sed script to do the
necessary edits. It would be nice to get a quick fix in, so the nightly HTML
documentation is more useful.

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


-- 
Brian Helba
Medical Imaging
Kitware, Inc.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/vtk-developers/attachments/20110405/7969ef6b/attachment.html>