[petsc-dev] Documentation comment support

[Karl Rupp]

Hey,

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

Yes, something like
  ksp/ksp/examples/tutorials/ex1.c
  ksp/ksp/examples/tutorials/ex2.c
  ...
  ksp/ksp/examples/tutorials/ex59.c
  ksp/pc/examples/tutorials/ex1.c
  ksp/pc/examples/tutorials/ex2.c
  ... and so on ...

I expect that doxygen issues a warning if the file is not found. 
Conversely, examples not present in the list are silently ignored, hence 
I prefer the automatic creation/update of the list from a script.


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

Yes, I know. The \example directives are only used to indicate the 
presence of the example file. Everything else is then done automatically 
by doxygen, so you don't need to specify manually which feature/function 
is used in which example. You could, however, use the \example directive 
to further add a description how each feature is used in each of the 
examples.

In the context of MatSetValuesBlockedLocal(), after declaring the list 
of examples in a separate header file, you get something like

  MatSetValuesBlockedLocal()
    Synopsis
    Function description
    Examples: ex1.c
              ex3.c
              ...

(This is pretty much the same what we have now)

However, with clever (non-automatic) placement of the \example directive 
you could even achieve

  MatSetValuesBlockedLocal()
    Synopsis
    Function description
    Examples: ex1.c - Here it is used without MPI
              ex3.c - Explains how to use it efficiently with MPI
              ...

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

Yes, I'll just apply the filter locally and push the generated docs to 
some webspace. Maybe I can even teach doxygen to accept the current 
syntax...

Best regards,
Karli