[gmx-developers] doxygen: public documentation, but is not in installed header

[Teemu Murtola]

Hi,

On Mon, Apr 20, 2015 at 12:20 PM, David van der Spoel <spoel at xray.bmc.uu.se>
wrote:

> using doxygen brings about a whole new level of debugging.


Doxygen has its quirks (unfortunately quite many of those), and we have
some extra checks to make sure people are not bitten by those quirks (and
don't leave solving all the problems for others). Most of the stuff is
documented at
  <
http://jenkins.gromacs.org/job/Documentation_Gerrit_Nightly/javadoc/doxygen/html-lib/page_doxygen.xhtml
>
(should update automatically whenever new documentation is merged from
Gerrit, but I'm not sure whether that works currently, as the last build is
a month old).


> In this case I have in the preamble of my code:
>
> /*! \internal \file
>  * \brief
>  * Declares gmx::EnergyFrame
>  *
>  * \author David van der Spoel <david.vanderspoel at icm.uu.se>
>  * \ingroup module_energyanalysis
>  */
>
> then I got the message in the subject which seems to complain I have *TOO
> MUCH* documentation, e.g.:
>

For Doxygen, the file-level documentation is very loosely coupled with
classes within that file. In particular, whether you document the file or
not, classes within that file will still always appear in the documentation
if they are documented. So in order to not pollute the documentation for
the installed/public headers, we have an extra check that classes from
non-installed headers should not be documented as public, since this is
very easy to miss otherwise.

Any clue how to resolve this?


You need to use \internal also in the beginning of every class
documentation within that file. This is all documented on the page linked
above. ;)

Best regards,
Teemu
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://maillist.sys.kth.se/pipermail/gromacs.org_gmx-developers/attachments/20150424/90f9660f/attachment-0001.html>