[petsc-dev] Documentation comment support

[Jed Brown]

On Sat, Dec 22, 2012 at 4:16 AM, Karl Rupp <rupp at mcs.anl.gov> wrote:

> Hey,
>
>
> > This feature is cool
> >
> > http://llvm.org/releases/3.2/**docs/ClangReleaseNotes.html<http://llvm.org/releases/3.2/docs/ClangReleaseNotes.html>
>
> somewhat ;-) I don't see how/why it is better than
> $> doxygen | grep warning
> (or any other tool with similar purpose).
>

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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20121222/fd42bac5/attachment.html>