Hi All,<br><br>Here is the Gerrit branch that allows Description blocks to not have white space separation.<br><br><a href="http://review.source.kitware.com/#change,1327">http://review.source.kitware.com/#change,1327</a><br>

<br><div class="gmail_quote">On Wed, Apr 6, 2011 at 8:39 AM, Robert Maynard <span dir="ltr"><<a href="mailto:robert.maynard@kitware.com">robert.maynard@kitware.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">

Hi,<br>
<br>
I am currently testing a small change to the perl script that will<br>
allow subsequent blocks that immediately follow tags, qualifiers, or<br>
other Description blocks to be translated.<br>
<div><div></div><div class="h5"><br>
<br>
On Tue, Apr 5, 2011 at 2:46 PM, Will Schroeder<br>
<<a href="mailto:will.schroeder@kitware.com">will.schroeder@kitware.com</a>> wrote:<br>
> Fix the script (if possible) IMO.<br>
> W<br>
><br>
> On Tue, Apr 5, 2011 at 2:33 PM, David Cole <<a href="mailto:david.cole@kitware.com">david.cole@kitware.com</a>> wrote:<br>
>><br>
>> On Tue, Apr 5, 2011 at 2:26 PM, Brian Helba <<a href="mailto:brian.helba@kitware.com">brian.helba@kitware.com</a>><br>
>> wrote:<br>
>>><br>
>>> There won't be much drudgery, I already have a bash/sed script to do the<br>
>>> necessary edits.<br>
>><br>
>> But the edits are unnecessary if the script is fixed....<br>
>><br>
>><br>
>>><br>
>>> It would be nice to get a quick fix in, so the nightly HTML documentation<br>
>>> is more useful.<br>
>><br>
>> It has been this way for a long, long time. It would be better to get the<br>
>> right fix (rather than quick) in and avoid the unnecessary edits.<br>
>><br>
>> But maybe that's just me....<br>
>><br>
>> Feel free to resolve this however you think is best.<br>
>><br>
>><br>
>>><br>
>>> The issue with the script is that not enough analysis is performed within<br>
>>> each loop iteration to determine where a block of grouped comments /<br>
>>> function declarations ends. After a "// Description" tag is found at the<br>
>>> beginning of an iteration, the script expects an arbitrary number of<br>
>>> comment, code or macro lines. A special case could be added inside the loop:<br>
>>> while inside a Description block, if another "// Description" tag is<br>
>>> encountered, end the outer block and continue to another iteration.<br>
>>><br>
>>> On Tue, Apr 5, 2011 at 1:18 PM, David Cole <<a href="mailto:david.cole@kitware.com">david.cole@kitware.com</a>><br>
>>> wrote:<br>
>>>><br>
>>>> I think it would be time better spent to fix the actual problem.<br>
>>>><br>
>>>> I don't think it's intentional that the script requires a newline<br>
>>>> preceding the "// Description" blocks... I can't see from the code why that<br>
>>>> would be the case. Guess my perl is rusty.<br>
>>>><br>
>>>> Is there a brave perl volunteer listening that can save Brian from the<br>
>>>> drudgery of adding blank lines here and there...?<br>
>>>><br>
>>>><br>
>>>> On Tue, Apr 5, 2011 at 1:02 PM, Brian Helba <<a href="mailto:brian.helba@kitware.com">brian.helba@kitware.com</a>><br>
>>>> wrote:<br>
>>>>><br>
>>>>> In a number of cases, Utilities/Doxygen/<a href="http://doc_header2doxygen.pl" target="_blank">doc_header2doxygen.pl</a> is<br>
>>>>> failing to parse and translate "// Description:" blocks in VTK header files<br>
>>>>> into actual Doxygen-style comment blocks. Specifically, 351 function<br>
>>>>> descriptions across 101 classes appear to be affected.<br>
>>>>><br>
>>>>> The issue can arise when the line "// Description:" is not preceded by<br>
>>>>> a newline. The Perl script does check for other documentation tags (//BTX,<br>
>>>>> //ETX) and qualifiers (public, etc.) but only correctly parses the very<br>
>>>>> first block; subsequent blocks that immediately follow tags, qualifiers, or<br>
>>>>> other Description blocks fail to be translated.<br>
>>>>><br>
>>>>> The long-term fix is to make Utilities/Doxygen/<a href="http://doc_header2doxygen.pl" target="_blank">doc_header2doxygen.pl</a><br>
>>>>> more robust, as it already attempts to correct for non-conforming code in<br>
>>>>> some cases. Also, the standards at<br>
>>>>> <a href="http://www.vtk.org/Wiki/VTK_Coding_Standards#Documentation_Standards" target="_blank">http://www.vtk.org/Wiki/VTK_Coding_Standards#Documentation_Standards</a> do not<br>
>>>>> seem to make it adequately clear that a newline should precede all<br>
>>>>> declaration blocks that include a "// Description:". If this is the<br>
>>>>> standard, it should be clarified; if not, fixing the Perl script would be a<br>
>>>>> much higher priority.<br>
>>>>><br>
>>>>> Meanwhile, I'm planning to directly fix the affected documentation by<br>
>>>>> simply inserting newlines. Should I modify only the places where parsing<br>
>>>>> errors actually do occur, or should I add newlines before all "//<br>
>>>>> Description:" blocks that don't already have them (to conform with the<br>
>>>>> potential standard), even if they are being parsed correctly?<br>
>>>>><br>
>>>>> Brian Helba<br>
>>>>><br>
>>>>> _______________________________________________<br>
>>>>> Powered by <a href="http://www.kitware.com" target="_blank">www.kitware.com</a><br>
>>>>><br>
>>>>> Visit other Kitware open-source projects at<br>
>>>>> <a href="http://www.kitware.com/opensource/opensource.html" target="_blank">http://www.kitware.com/opensource/opensource.html</a><br>
>>>>><br>
>>>>> Follow this link to subscribe/unsubscribe:<br>
>>>>> <a href="http://www.vtk.org/mailman/listinfo/vtk-developers" target="_blank">http://www.vtk.org/mailman/listinfo/vtk-developers</a><br>
>>>>><br>
>>>>><br>
>>>><br>
>>><br>
>>><br>
>>><br>
>>> --<br>
>>> Brian Helba<br>
>>> Medical Imaging<br>
>>> Kitware, Inc.<br>
>>><br>
>><br>
>><br>
>> _______________________________________________<br>
>> Powered by <a href="http://www.kitware.com" target="_blank">www.kitware.com</a><br>
>><br>
>> Visit other Kitware open-source projects at<br>
>> <a href="http://www.kitware.com/opensource/opensource.html" target="_blank">http://www.kitware.com/opensource/opensource.html</a><br>
>><br>
>> Follow this link to subscribe/unsubscribe:<br>
>> <a href="http://www.vtk.org/mailman/listinfo/vtk-developers" target="_blank">http://www.vtk.org/mailman/listinfo/vtk-developers</a><br>
>><br>
>><br>
><br>
><br>
><br>
> --<br>
> William J. Schroeder, PhD<br>
> Kitware, Inc.<br>
> 28 Corporate Drive<br>
> Clifton Park, NY 12065<br>
> <a href="mailto:will.schroeder@kitware.com">will.schroeder@kitware.com</a><br>
> <a href="http://www.kitware.com" target="_blank">http://www.kitware.com</a><br>
> (518) 881-4902<br>
><br>
> _______________________________________________<br>
> Powered by <a href="http://www.kitware.com" target="_blank">www.kitware.com</a><br>
><br>
> Visit other Kitware open-source projects at<br>
> <a href="http://www.kitware.com/opensource/opensource.html" target="_blank">http://www.kitware.com/opensource/opensource.html</a><br>
><br>
> Follow this link to subscribe/unsubscribe:<br>
> <a href="http://www.vtk.org/mailman/listinfo/vtk-developers" target="_blank">http://www.vtk.org/mailman/listinfo/vtk-developers</a><br>
><br>
><br>
><br>
<br>
<br>
<br>
--<br>
</div></div><font color="#888888">Robert Maynard<br>
</font></blockquote></div><br><br clear="all"><br>-- <br>Robert Maynard<br>