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
