[petsc-dev] PETSc goes Doxygen!?

[Karl Rupp]

Hi Jed,

>     The listing of
>     http://krupp.iue.tuwien.ac.at/__petsc-doxygen/ksp_2ksp___2examples_2tutorials_2ex4_8c-__example.html
>     <http://krupp.iue.tuwien.ac.at/petsc-doxygen/ksp_2ksp_2examples_2tutorials_2ex4_8c-example.html>
>     is now identical with the one Barry mentioned - except for a
>     violation of coding style on lines 49/50 that already affects the
>     sources. I'll send a separate email on that.
>
>
> Why aren't PetscScalar and PetscReal linkified? And all the
> PetscLogEventRegister/Begin/End/...

I disabled the automatic documentation of undocumented entities, that's 
why links got lost.


> Are these hash URLs stable? What information goes into the hash?

That's a bit of a hodgepodge. Examples paths are basically mapped 1:1 to 
the URL, the exceptions being '/', which is mapped to '_2', and '.', 
which is mapped to '_8'.

The MD5 hashes in use are said to be stable, as they are based on e.g. 
the function name and the parameters:
http://stackoverflow.com/questions/8145278/making-stable-names-for-doxygen-html-docs-pages
For example, the following input is used for the MD5 hash of DMSetUp():
PETSC_EXTERN PetscErrorCode DMSetUpDMSetUp(DM)

Presumably the reason for introducing hashes rather than using function 
names directly is the overloading mechanism in various languages.


>     - Examples now carry correct line numbers even with things stripped
>     out. This required a small Doxygen patch, which I've sent to the
>     developers for inclusion in the next release.
>
>     - Private functions no longer show up in the various modules (this
>     was caused by /*MC incorrectly being interpreted as part of a
>     function documentation)
>
>     There are still a bunch of private data structures shown. There is
>     no consistent way of determining whether a data structure is private
>     or not. The underscore could be a criterion, but then it misses some
>     rather important things such as DM_Plex:
>     http://krupp.iue.tuwien.ac.at/__petsc-doxygen/structDM__Plex.__html
>     <http://krupp.iue.tuwien.ac.at/petsc-doxygen/structDM__Plex.html>
>     (Note that I could further improve the data field documentation if I
>     were allowed to touch sources and replace /* ... */ by /** ... */)
>
>
> As with all implementation structures, DM_Plex is not user-visible. The
> user-visible type is DM and they use DM* and DMPlex* interfaces. The
> type documentation is with the type name: DMPLEX ("plex").

In light of what Matt said, it's probably best to have two separate 
doxygen outputs?
- One for users, containing only the things we want them to use.
- The second is for (new) developers, where additional information is 
available. Ideally, the intersection of the two is an empty set, so the 
second is of little value for new users and thus they will more likely 
refrain from abusing it.

Best regards,
Karli