<div class="gmail_quote">On Tue, Apr 5, 2011 at 2:26 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;">
There won't be much drudgery, I already have a bash/sed script to do the
necessary edits.</blockquote><div><br>But the edits are unnecessary if the script is fixed....<br> <br></div><div> </div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
It would be nice to get a quick fix in, so the nightly
HTML documentation is more useful.<br></blockquote><div><br>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.<br><br>But maybe that's just me....<br>
<br>Feel free to resolve this however you think is best.<br><br> <br></div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<br>
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.<div><div></div><div class="h5"><br><br><div class="gmail_quote">On Tue, Apr 5, 2011 at 1:18 PM, David Cole <span dir="ltr"><<a href="mailto:david.cole@kitware.com" target="_blank">david.cole@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;">
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"><div><div></div><div>On Tue, Apr 5, 2011 at 1:02 PM, Brian Helba <span dir="ltr"><<a href="mailto:brian.helba@kitware.com" target="_blank">brian.helba@kitware.com</a>></span> wrote:<br>
</div></div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;"><div><div></div><div>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></div></div>_______________________________________________<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>
</blockquote></div><br><br clear="all"><br></div></div><font color="#888888">-- <br>Brian Helba<br>Medical Imaging<br>Kitware, Inc.<br><br>
</font></blockquote></div><br>