[petsc-dev] Documentation comment support

[Karl Rupp]

Hi Jed,

 > (...)
 >
>     Note the small 'search' field on the top right for both variants.
>
>
> They should make that box 10x bigger. ;-)

True :-)


> Those cross-references still look one-way. Is there a way to make a
> two-way link, so that anywhere I mention X, the man page for X includes
> a link the other way?

I could only find a manual way:
http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdexample
HTML output is here:
http://www.stack.nl/~dimitri/doxygen/manual/examples/example/html/examples.html

Basically, you just need to set EXAMPLE_PATH to the respective example 
directories. It creates two-way references, but it does not link 
directly to the respective *line*. It should be possible to inject such 
\example blocks automatically into source files before creating the 
documentation...


>     If I'm not mistaken, Eigen always preferred HTML manuals (user and
>     reference) over a PDF version. With the issues of linking into PDFs
>     showing up repeatedly, having everything in one place seems to be
>     the better bet. It doesn't need to be Doxygen, though.
>
>
> What are the alternatives? Doxygen seems to be much more popular than
> any alternative for API documentation (man pages). For HTML manuals,
> there is doxygen (best integration with API docs), Sphinx (popular, but
> only well integrated with Python), wikis (no a priori integration, but
> maybe hackable), and LaTeX (one-way integration in PETSc by our
> preprocessing).

I'm not aware of other alternatives. What I was trying to point out is 
that I'm not a Doxygen militant, I'm open to whichever tool provides the 
best results.

I just went over the list of new features and was actually surprised by 
the many new features added to Doxygen during 2012, particularly 
Markdown support since 1.8.0:
   http://www.stack.nl/~dimitri/doxygen/changelog.html
Thus, Doxygen is presumably the better option over wikis anyway, even if 
we ignore the burden of hacking existing wiki systems.

Best regards,
Karli