[petsc-dev] Documentation comment support

[Karl Rupp]

Hi Jed,

 >     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.
>

yes, I know that this is not precisely what you wanted. Consequently I 
added 'It should be possible to inject such \example blocks 
automatically into source files before creating the documentation...'

Further playing with the
  \example
feature showed that it is sufficient to make the examples known to the 
Doxygen parser once. Hence, all we need to do is to auto-generate a 
simple header file containing nothing but a description of the examples, 
e.g.

--- file examples.h begin ---

/** \example path/to/ex1.c
  * This is an example of how to use A.
  */

/** \example path/to/ex2.c
  * This is an example of how to use B.
  */

--- file examples.h end ---

We can create this automatically with a rather simple shell or Perl 
script, reusing the description in help[] at the beginning of each example.

Then, ex1.c and ex2.c automatically show up as examples in the 
documentation of A and B. Even better, ex1.c and ex2.c receive anchors 
to the respective line of the *first use* of A and B. :-)


>     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.

The context switch is a point, yes. For the user manual part, the 
context switch is comparable to manipulating LaTeX files by using 
dedicated source files for the Doxygen input (i.e. take the current .tex 
files, strip off some LaTeX specifics, then \include them in Doxygen). 
This is typically done offline just as updating the reference code 
comments. A cron script at the webserver can make sure that the doxygen 
docs are rebuilt every night.

In light of the now essentially automatic 'example.h' workaround 
described above we get the two-way-references for free. Since both the 
reference and the user manual is built within the same run, we get 
warnings issued whenever some link becomes invalid. For example, this 
should minimize documentation errors when renaming functions.

I think I'm able to come up with a sample Doxygen documentation of PETSc 
towards the weekend.

Best regards,
Karli