[vtk-developers] Documentation improvement

[Marcus D. Hanwell]

On Wednesday 18 November 2009 10:31:54 David Doria wrote:
> I started to look into the documentation issues. Looking at the
> current doxygen pages (e.g.
> http://www.vtk.org/doc/nightly/html/classvtkLandmarkTransform.html)
> there is a massive quantity of "easy" problems (I've started a list
> here: http://www.vtk.org/Wiki/VTK#Documentation_Improvement)
> 
> Is there anyway I can get write access if I sign a contract that I
> will not modify anything except comments? I can at least go through
> and fix the "easy" problem like the doxygen comments are being drawn
> from the wrong functions because many of them are missing/etc/etc. As
> I am doing that, it should be easy to compile a list of the "harder"
> documentation improvements of the type "what is p? what is N? What
> does this function do?" that other developers can help with.
> 
David Doria and I have been looking into some of the documentation issues. It 
looks like one of the issues as you have pointed out is the very first doxygen 
comment block being used for all functions with no doxygen comment. This 
appears to be the perl script falling down, somewhere around line 530 
(Sebastien gave us some pointers on this).

The file in question is Utilities/Doxygen/doc_header2doxygen.pl, so if some 
Perl guru could fix this to ensure that the most recent comment is used rather 
than the first this would improve a large amount of the documentation. I will 
try to take a look at it when I have some time, but it has been a good few 
years since I hacked at any Perl code.

Marcus
-- 
Marcus D. Hanwell, Ph.D.
R&D Engineer, Kitware Inc.
(518) 881-4937