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 preceding the "// Description" blocks... I can't see from the code why that would be the case. Guess my perl is rusty.<br>
<br>Is there a brave perl volunteer listening that can save Brian from the drudgery of adding blank lines here and there...?<br><br><br><div class="gmail_quote">On Tue, Apr 5, 2011 at 1:02 PM, Brian Helba <span dir="ltr"><<a href="mailto:brian.helba@kitware.com">brian.helba@kitware.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">In a number of cases, Utilities/Doxygen/<a href="http://doc_header2doxygen.pl" target="_blank">doc_header2doxygen.pl</a> 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.<br>


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


<br>The long-term fix is to make Utilities/Doxygen/<a href="http://doc_header2doxygen.pl" target="_blank">doc_header2doxygen.pl</a> more robust, as it already attempts to correct for non-conforming code in some cases. Also, the standards at <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 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.<br>


<br>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?<br>
<font color="#888888">

<br>Brian Helba<br>
</font><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 <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></blockquote></div><br>