[petsc-dev] Documentation comment support

[Karl Rupp]

Hi Jed,

 > Doxygen has full semantic understanding of the body of functions,
> including ability to trace through function calls within a compilation
> unit to determine whether the argument usage matches its declaration? I
> never thought it was that sophisticated.
>
> Is there a way to make Doxygen provide "used from" (especially examples)
> and two-way cross-references (.seealso is one-way)? What about
> organizing functions by "level" or some other tag? I'm not a fan of
> sowing, but I have a yet to see doxygen-generated man pages that were
> really more useful.
>
> Also, do you know a way to render an HTML version of a user's manual
> (written in LaTeX, reStructuredText, or some other markup) that can be
> robustly cross-referenced with the man pages? PETSc's LaTeX
> preprocessing gets us one direction (click on function name in PDF to
> get man page), but lack of the other direction is a serious problem in
> my opinion. A I'd really like to have the man page -> user's manual
> links created automatically (anywhere the function is mentioned in the
> user's manual, just like the index), but also support explicit links
> from the body of the man page.
>
> The closest thing I've seen is breathe
> (http://michaeljones.github.com/breathe/) which tries to combine doxygen
> and sphinx, but development has slowed and it's still kinda rough.

Aside from the usual warnings a compiler has to issue if it detects a 
potentially faulty use of a variable, is there really anything beyond 
matching comments with the actual variable declarations? The release 
notes just state:

'Clang parses the comments and can detect syntactic and semantic errors 
in comments.'

So even though in principle it *could* do all the nice traces and such, 
I doubt that developers will make clang an 
all-in-one-suite-for-everything including a documentation generator, 
because this monolithic thingy is exactly what they complain about in GCC.

As for the cross-referencing manuals and man-pages: I talked with Barry 
about that two weeks ago, since I had to produce a HTML version of my 
PhD thesis:
   http://www.iue.tuwien.ac.at/phd/rupp/
I used tex4ht, which is still not perfect, but worked with reasonable 
effort. At least one can get reasonable HTML output from LaTeX.
Maybe one could customize the anchors so that one can not only reference 
out of the HTML output, but also *into* the output - however, I still 
have to check that...

About two years ago I went through the deal.II documentation generator, 
at that time it used quite a number of scripts in order to extract the 
necessary information from the files. These were required to overcome 
some of the deficiencies of Doxygen at that time, e.g. math fonts and I 
think some cross-links. Meanwhile Doxygen also supports math formulae, 
and a couple of additional structuring mechanisms. I haven't tried any 
of the three items you mentioned, though...

Best regards,
Karli