[petsc-dev] PETSc goes Doxygen!?

[Jed Brown]

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>