[vtk-developers] Documentation Parsing

David Cole david.cole at kitware.com
Tue Apr 5 14:33:31 EDT 2011


Just one more thing:

If you don't fix the script, this problem will creep back in as people add
things and move things around....


On Tue, Apr 5, 2011 at 2:33 PM, David Cole <david.cole at kitware.com> wrote:

> 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://public.kitware.com/pipermail/vtk-developers/attachments/20110405/abc1aed7/attachment.html>


More information about the vtk-developers mailing list