On Tue, Jan 15, 2013 at 4:26 PM, Karl Rupp <rupp at mcs.anl.gov> wrote:
> I disabled the automatic documentation of undocumented entities, that's > why links got lost. > But all of those _are_ documented. > > 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. > >> 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). -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20130115/18038365/attachment.html>
