[vtk-developers] Documentation Parsing

[Robert Maynard]

Hi,

I am currently testing a small change to the perl script that will
allow subsequent blocks that immediately follow tags, qualifiers, or
other Description blocks to be translated.


On Tue, Apr 5, 2011 at 2:46 PM, Will Schroeder
<will.schroeder at kitware.com> wrote:
> Fix the script (if possible) IMO.
> W
>
> 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.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.
>>>
>>
>>
>> _______________________________________________
>> 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
>>
>>
>
>
>
> --
> William J. Schroeder, PhD
> Kitware, Inc.
> 28 Corporate Drive
> Clifton Park, NY 12065
> will.schroeder at kitware.com
> http://www.kitware.com
> (518) 881-4902
>
> _______________________________________________
> 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
>
>
>



-- 
Robert Maynard