[gmx-developers] Doxygen sections and visibility

[Eric Irrgang]

Hi all,

I have a few questions about the conventions and intentions of the
generated dev docs. Fundamentally, I'm trying to figure out to what degree
a viewer of the "full" documentation can determine whether a class page
documents something in the public API, library API, or neither.

First, is there intended to be a one-to-one correspondence between
section-based visibility and grouping? I.e. if \libinternal (sets doc
section) is not accompanied by \inlibraryapi (sets doc group) for class
documentation, is it an error or an implication that the author is
observing "the library API documentation should not contain things that
other modules in GROMACS can or should never call"? Does that statement in
the Doxygen suggestions imply that there are things in the library API that
should not be part of the library API documentation?

For classes and documentation scopes that can be in multiple groups, it is
helpful to have the group links at the top of the docs indicating both the
API and module, but I am not sure how to interpret it when I see only the
module link (and the entity is a class, which should be allowed to have
multiple groups). Is there a way I can easily tell from the generated full
docs whether I'm looking at something that was marked "\internal" versus
something that was just not grouped \inpublicapi or \inlibraryapi? E.g. how
would I tell from the library documentation whether a free function in a
module is part of the public API or not?

Would it be reasonable to add another group to distinguish entities
considered too localized to live in the library API? Alternatively, in
order to label free functions and things that can't have both a module
group and an API group, does anyone know of some other Doxygen trick to add
some sort of "badge" instead, such as the way "virtual" and "inline" labels
get added to the detailed descriptions? It seems a bit messy, but I would
think something could be done with a \cond block for \libinternal and
\internal, but does the default section have a name?

Thank you in advance for any enlightenment you can offer,
Eric
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://maillist.sys.kth.se/pipermail/gromacs.org_gmx-developers/attachments/20170220/2207f675/attachment.html>