[vtk-developers] Documentation Parsing

Brian Helba brian.helba at kitware.com
Tue Apr 5 13:02:28 EDT 2011


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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/vtk-developers/attachments/20110405/2ba32e2a/attachment.html>


More information about the vtk-developers mailing list