<div>Hi All,</div><div><br></div>Attached is a script (also few dependent files)I had written to convert documentation from vtk format (adapted to slight user modification too) to doxygen format. <div><br></div><div>At the outset I should warn you that the script is in written with secret alien technology (common lisp :) ). <div>
However they have worked well for me I have successfully used it for converting vtk-style comments to doxygen style for large number of files in the Titan project.</div><div><br></div><div>It uses PPCRE (Portable Perl-Compatible Regular Expression library) <a href="http://weitz.de/cl-ppcre/">http://weitz.de/cl-ppcre/</a> which means that the regular expressions are perl based and at one place it actually uses a one of the perl scripts from VTK itself.</div>
<meta http-equiv="content-type" content="text/html; charset=utf-8"><div>It has modifications and corrections for some of the problems I faced with the VTK perl scripts.</div><div><br></div><div>Its meant to be run from the common lisp prompt (cl >) and lets one do things like.</div>
<div><br></div><div>1. Collect a list of *.cxx or *.h files in a given directory </div><div> </div><div> Look for "(defparameter H ..." and "(defparameter CXX ..." and replace with whatever directory you please.</div>
<div><br></div><div>2. Iterating through the list of files and deleting different types of of headers from a list of .cxx or .h files</div><div><br></div><div>cl > (iterate-n-apply 'delete-doubleline-header H)</div>
<div>cl > (iterate-n-apply 'delete-doubleline-header CXX) </div><div>cl > (iterate-n-apply 'delete-singleline-header H)</div><div>cl > (iterate-n-apply 'delete-singleline-header CXX)</div><div><br></div>
<div>3. Inserting headers.</div><div><br></div><div>cl > (iterate-n-apply 'insert-header H)</div><div>cl > (iterate-n-apply 'insert-header CXX)</div><div><br></div><div>4. Replacing class documentation to doxygen style</div>
<div> </div><div>cl > (iterate-n-apply 'loop-class H)</div><div><br></div><div>5. Replace method documentation to doxygen style</div><div><br></div><div>cl > (iterate-n-apply 'loop-method H)</div><div><br></div>
<div>You will also see that it loads shelisp.lisp (shebang lisp) which is my unfinished attempt to make it user friendly (SORRY :( ). </div><div><br></div><div>-Nix</div><div> </div><div> </div><div><div><div><br></div><div>
<br><br><div class="gmail_quote">On Wed, Apr 6, 2011 at 9:31 AM, Robert Maynard <span dir="ltr"><<a href="mailto:robert.maynard@kitware.com" target="_blank">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 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" target="_blank">http://review.source.kitware.com/#change,1327</a><div>
<div></div><div><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" target="_blank">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><br>
<br>
On Tue, Apr 5, 2011 at 2:46 PM, Will Schroeder<br>
<<a href="mailto:will.schroeder@kitware.com" target="_blank">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" target="_blank">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" target="_blank">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" target="_blank">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" target="_blank">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" target="_blank">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></div></div>-- <br><font color="#888888">Robert Maynard<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></div></div>
</div></div>