[petsc-dev] Documentation comment support

[Jed Brown]

I suppose this all-doxygen example is fairly good.

http://openmesh.org/Documentation/OpenMesh-Doc-Latest/index.html

Deal.II's examples are also great, and I guess they could have easily added
more manual/concept pages.

Can a doxygen user think of nice ways to do

1. two-way "related" links?
2. structured annotation like Level (implies its own topical index) and
Collective?
3. indicate Fortran auto/custom/none without clutter?

On Sat, Dec 22, 2012 at 9:32 AM, Jed Brown <jedbrown at mcs.anl.gov> wrote:

> 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/57fda32a/attachment.html>