[IPOL discuss] comments needed : [draft] IPOL Software Guidelines v.1

[Juan Cardelino]

>
> The key is that it allows for automatic documentation, for example, with
> doxygen.
>

I agree with this, however we could think going beyond. There are
other experiences who put a particular emphasis in code sharing and
documentation.
If you take a look at the ITK Software guide [1] or any Insight
Journal Submission [2], you will see that in addition to doxygen they
have and automated way to extract comments along with code snippets,
which ends up written in latex->pdf document. These comments are
extracted not only from file, function, and variables, but also from
comments interleaved with the code. This pdf is way more readable, and
improves code understanding a lot. It is written as a continuous prose
compared with the fragmentation of the doxygen output. Of course again
this is extra work, but it is already done in an open source way, so
it would be a matter of copying it.
The only requirement for this to run, will be to ask the author to put
some tags in the interleaved comments, like BEGIN: IPOL, END: IPOL or
something.

For the rest, I mostly agree with what has been said so far.

Best,
        Juan

[1] ITK software guide. www.itk.org/ItkSoftwareGuide.pdf. See Chapter
7. Pages 295-299.
[2] Insight Journal. See this example:
http://www.insight-journal.org/browse/publication/840, go to the "view
paper" link on the right.