[petsc-dev] Documentation comment support

[Jed Brown]

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

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

Presumably this can be a list of A01 to A99?


>
> /** \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.
>

It's more than that. There are examples that use
MatSetValuesBlockedLocal(), for example, but their primar y purpose is
something else. We'd like them to be linked automatically. Distinguishing
"dedicated" examples (whose sole purpose is demonstrating that interface)
might be cool, but most interfaces won't have a dedicated 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. :-)


Cool.


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

Cool, I look forward to seeing it. Initially, it'll be best to write an
input filter that reformats sowing comments into Doxygen comments (and
perhaps inserts other stuff). If we like the result, we could apply the
change everywhere, but we'll need to also update Fortran stub handling
before we can leave sowing format in the source tree.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20130108/31ed74a0/attachment.html>