[petsc-dev] PETSc goes Doxygen!?

[Karl Rupp]

Hey,

>     I disabled the automatic documentation of undocumented entities,
>     that's why links got lost.
>
>
> But all of those _are_ documented.

At least for PetscScalar and PetscReal this is unfortunately not the case:

include/petscmath.h"

#if defined(PETSC_USE_COMPLEX)
typedef PetscComplex PetscScalar;
  ....
#else /* PETSC_USE_COMPLEX */
typedef PetscReal PetscScalar;
#define MPIU_SCALAR MPIU_REAL

For PetscLogEventXYZ() there must be some error in transforming the 
documentation tag /*@C, I'll check.

>         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
>     <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.
>
>
> Okay, so if we add a const to an argument (for example), its man page is
> going to move to a different URL. (I care because people will click
> links from old email threads and it's not great to have an hash lead to
> 404 without suggested alternatives.

I agree that the hashes are not at all satisfactory. Ideally the URLs 
are the same as what is in use now - I'll see what I can do.



>         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.
>
>
> Sure, though if we're going to provide a "developer" version, it should
> probably include everything (searching two places sucks).

In such case we should place suitable warnings/links in the 'developer' 
version so that actual 'users' are guided back to 'their' version.

Best regards,
Karli