[petsc-dev] Documentation comment support

[Jed Brown]

On Tue, Jan 8, 2013 at 11:35 AM, Karl Rupp <rupp at mcs.anl.gov> wrote:

> I could only find a manual way:
> http://www.stack.nl/~dimitri/**doxygen/manual/commands.html#**cmdexample<http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdexample>
>

But that is writing "\example someexample.cpp" in the API man page. I want
that link automatically when we _call_ the function from any example in
EXAMPLE_PATH, without messing with the API man page.


>
> HTML output is here:
> http://www.stack.nl/~dimitri/**doxygen/manual/examples/**
> example/html/examples.html<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<http://www.stack.nl/~dimitri/doxygen/changelog.html>
>

Yeah, Markdown support increased my interest significantly.


> Thus, Doxygen is presumably the better option over wikis anyway, even if
> we ignore the burden of hacking existing wiki systems.
>

This isn't clear to me. Doxygen is all static so even minor doc fixes
necessarily involve a context switch (to find the file in your editor) and
you don't see results immediately. Gollum and Gitit are hosted in a normal
repository so you can work on them offline and use normal tools for batch
processing. Writing a Doxygen input filter to convert [[Some Wiki Page]] in
source code to fully marked up links would be very easy, so the only
"hacking" would be the reverse links (from wiki to API man page). So I'm
not sold either way.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20130108/d589e23b/attachment.html>