1 Using Doxygen {#page_doxygen}
4 This page documents how Doxygen is set up in the \Gromacs source tree,
5 as well as guidelines for adding new Doxygen comments. Examples are included,
6 as well as tips and tricks for avoiding Doxygen warnings. The guidelines focus
7 on C++ code and other new code that follows the new module layout.
8 Parts of the guidelines are still applicable to documenting older code (e.g.,
9 within `gmxlib/` or `mdlib/`), in particular the guidelines about formatting
10 the Doxygen comments and the use of \c \\internal.
11 \ref page_codelayout documents the overall structure of the documentation.
13 To get started quickly, you only need to read the first two sections to
14 understand the overall structure of the documentation, and take a look at the
15 examples at the end. The remaining sections provide the details for
16 understanding why the examples are the way they are, and for more complex
17 situations. They are meant more as a reference to look up solutions for
18 particular problems, rather than single-time reading. To understand or find
19 individual Doxygen commands, you should first look at Doxygen documentation
20 (http://www.stack.nl/~dimitri/doxygen/manual/index.html).
25 The \Gromacs source tree is set up to produce three different levels of Doxygen
28 1. Public API documentation (suffix `-user`), which documents functions and
29 classes exported from the library and intended for use outside the \Gromacs
31 2. Library API documentation (suffix `-lib`), which additionally includes
32 functions and classes that are designed to be used from other parts of
33 \Gromacs, as well as some guidelines that are mostly of interest to
35 3. Full documentation (suffix `-full`), which includes (nearly) all (documented)
36 functions and classes in the source tree.
38 Each subsequent level of documentation includes all the documentation from the
39 levels above it. The suffixes above refer to the suffixes of Doxygen input and
40 output files, as well as the name of the output directory. When all the
41 flavors have been built, the front pages of the documentation contain links to
42 the other flavors, and explain the differences in more detail.
44 As a general guideline, the public API documentation should be kept free of
45 anything that a user linking against an unmodified \Gromacs does not see.
46 In other words, the public API documentation should mainly document the
47 contents of installed headers, and provide the necessary overview of using
48 those. Also, verbosity requirements for the public API documentation are
49 higher: ideally, readers of the documentation could immediately start using the
50 API based on the documentation, without any need to look at the implementation.
52 Similarly, the library API documentation should not contain things that other
53 modules in \Gromacs can or should never call. In particular, anything declared
54 locally in source files should be only available in the full documentation.
55 Also, if something is documented, and is not identified to be in the library
56 API, then it should not be necessary to call that function from outside its
60 Building the documentation
61 ==========================
63 If you simply want to see up-to-date documentation, you can go to
64 http://jenkins.gromacs.org/job/Documentation_Nightly_master/javadoc/html-lib/index.xhtml
65 to see the documentation for the current development version.
66 Jenkins also runs Doxygen for all changes pushed to Gerrit for
67 release-5-0 and master branches, and the
68 resulting documentation can be viewed from the link posted by Jenkins. The
69 Doxygen build is marked as unstable if it introduces any Doxygen warnings.
71 You may need to build the documentation locally if you want to check the
72 results after adding/modifying a significant amount of comments. This is
73 recommended in particular if you do not have much experience with Doxygen.
74 It is a good idea to build with all the different settings to see that the
75 result is what you want, and that you do not produce any warnings.
76 For local work, it is generally a good idea to set `GMX_COMPACT_DOXYGEN=ON`
77 CMake option, which removes some large generated graphs from the documentation
78 and speeds up the process significantly.
80 All files related to Doxygen reside in the `docs/doxygen/` subdirectory in the source
81 and build trees. In a freshly checked out source tree, this directory contains
82 various `Doxyfile-*.cmakein` files. When you run CMake, corresponding files
83 `Doxyfile-user`, `Doxyfile-lib`, and `Doxyfile-full` are generated at the
84 corresponding location in the build tree. There is also a
85 `Doxyfile-common.cmakein`, which is used to produce `Doxyfile-common`.
86 This file contains settings that are shared between all the input files.
87 `Doxyfile-compact` provides the extra settings for `GMX_COMPACT_DOXYGEN=ON`.
89 You can run Doxygen directly with one of the generated files (all output will
90 be produced under the current working directory), or build one of the
91 `doc-user`, `doc-lib`, and `doc-full` targets. The targets run Doxygen in a
92 quieter mode and only show the warnings if there were any, and put the output
93 under `docs/html/doxygen/` in the build tree, so that the Doxygen build
94 cooperates with the broader `webpage` target. The `doc-all` target builds all three
95 targets with less typing.
97 The generated documentation is put under `html-user/`, `html-lib/`, and/or
98 `html-full/`. Open `index.xhtml` file from one of
99 these subdirectories to start browsing (for \Gromacs developers, the
100 `html-lib/` is a reasonable starting point). Log files with all Doxygen
101 warnings are also produced as `docs/doxygen/doxygen-*.log`, so you can inspect them after
104 You will need Doxygen 1.8.5 to build the current documentation. Other versions
105 may work, but likely also produce warnings. Additionally,
106 [graphviz](http://www.graphviz.org) and
107 [mscgen](http://www.mcternan.me.uk/mscgen/) are required for some graphs in
108 the documentation, and `latex` for formulas. Working versions are likely
109 available through most package managers. It is possible to build the
110 documentation without these tools, but you will see some errors and the related
111 figures will be missing from the documentation.
114 General guidelines for Doxygen markup
115 =====================================
117 Doxygen provides quite a few different alternative styles for documenting the
118 source code. There are subtleties in how Doxygen treats the different types of
119 comments, and this also depends somewhat on the Doxygen configuration. It is
120 possible to change the meaning of a comment by just changing the style of
121 comment it is enclosed in. To avoid such issues, and to avoid needing to
122 manage all the alternatives, a single style throughout the source tree is
123 preferable. When it comes to treatment of styles, \Gromacs uses the default
124 Doxygen configuration with one exception: `JAVADOC_AUTOBRIEF` is set ON to
125 allow more convenient one-line brief descriptions in C code.
127 Majority of existing comments in \Gromacs uses Qt-style comments (`/*!` and
128 `//!` instead of `/*``*` and `///`, \c \\brief instead of \c \@brief etc.),
129 so these should be used also for new documentation. There is a single
130 exception for brief comments in C code; see below.
132 Similarly, existing comments use `/*!` for multiline comments in both C and
133 C++ code, instead of using multiple `//!` lines for C++. The rationale is that
134 since the code will be a mixture of both languages for a long time, it is more
135 uniform to use similar style in both. Also, since files will likely transition
136 from C to C++ gradually, rewriting the comments because of different style
137 issues should not generally be necessary. Finally, multi-line `//!` comments
138 can work differently depending on Doxygen configuration, so it is better to
139 avoid that ambiguity.
141 When adding comments, ensure that a short brief description is always produced.
142 This is used in various listings, and should briefly explain the purpose of the
143 method without unnecessarily expanding those lists.
144 The basic guideline is to start all comment blocks with \c \\brief (possibly
145 after some other Doxygen commands).
146 If you want to avoid the \c \\brief for one-liners, you can use `//!`, but the
147 description must fit on a single line; otherwise, it is not interpreted as a
148 brief comment. Note in particular that a simple `/*!` without a \c \\brief
149 does not produce a brief description.
150 Also note that \c \\brief marks the whole following paragraph as a brief
151 description, so you should insert an empty line after the intended brief
154 In C code, `//` comments must be avoided because some compilers do not like
155 them. If you want to avoid the \c \\brief for one-liners in C code, use
156 `/*``*` instead of `//!`. If you do this, the brief description should not
157 contain unescaped periods except at the end. Because of this, you should
158 prefer `//!` in C++ code.
160 Put the documentation comments in the header file that contains the
161 declaration, if such a header exists.
162 Implementation-specific comments that do not influence how a method
163 is used can go into the source file, just before the method definition, with an
164 \c \\internal tag in the beginning of the comment block. Doxygen-style comments
165 within functions are not generally usable.
167 At times, you may need to exclude some part of a header or a source file such
168 that Doxygen does not see it at all. In general, you should try to avoid this,
169 but it may be necessary to remove some functions that you do not want to appear
170 in the public API documentation, and which would generate warnings if left
171 undocumented, or to avoid Doxygen warnings from code it does not understand.
172 Prefer \c \\cond and \c \\endcond to do this. If \c \\cond does not work for
173 you, you can also use \c \#ifndef `DOXYGEN`. If you exclude a class method in
174 a header, you also need to exclude it in the source code to avoid warnings.
180 The general guidelines on the style of Doxygen comments were given above.
181 This section introduces \Gromacs specific constructs currently used in Doxygen
182 documentation, as well as how \Gromacs uses Doxygen groups to organize the
185 Controlling documentation visibility
186 ------------------------------------
188 To control in which level of documentation a certain function appears, three
189 different mechanisms are used:
190 * Global Doxygen configuration. This is mainly used to include
191 declarations local to source files only in the full documentation.
192 You can find the details from the `Doxyfile-*.cmakein` files, and some of
193 them are also mentioned below on individual code constructs.
194 * The standard Doxygen command \c \\internal marks the documentation to be only
195 extracted into the full documentation (`INTERNAL_DOCS` is `ON` only for the
196 full documentation). This should be used as a first command in a comment
197 block to exclude all the documentation. It is possible to use \c \\internal
198 and \c \\endinternal to exclude individual paragraphs, but \c \\if `internal`
199 is preferred (see below).
200 In addition, \Gromacs-specific custom Doxygen command \c \\libinternal is
201 provided, which should be used the same way to exclude the documentation from
202 the public API documentation. This command expands to either \c \\internal
203 or to a no-op, depending on the documentation level.
204 * Doxygen commands \c \\if and \c \\cond can be used with section names
205 `libapi` and `internal` to only include the documentation in library API and
206 the full documentation, respectively. `libapi` is also defined in the full
207 documentation. These are declared using `ENABLED_SECTIONS` in the Doxygen
210 Examples of locations where it is necessary to use these explicit commands are
211 given below in the sections on individual code constructs.
213 Modules as Doxygen groups
214 -------------------------
216 As described in \ref page_codelayout, each subdirectory under `src/gromacs/`
217 represents a _module_, i.e., a somewhat coherent collection of routines.
218 Doxygen cannot automatically generate a list of routines in a module; it only
219 extracts various alphabetical indexes that contain more or less all documented
220 functions and classes. To help reading the documentation, the routines for a
221 module should be visible in one place.
223 \Gromacs uses Doxygen groups to achieve this: for each documented module, there
224 is a \c \\defgroup definition for the module, and all the relevant classes and
225 functions need to be manually added to this group using \c \\ingroup and
227 The group page also provides a natural place for overview documentation about
228 the module, and can be navigated to directly from the "Modules" tab in the
229 generated documentation.
231 Some notes about using \c \\addtogroup are in order:
232 * \c \\addtogroup only adds the elements that it directly contains into the
233 group. If it contains a namespace declaration, only the namespace is added
234 to the group, but none of the namespace contents are. For this reason,
235 \c \\addtogroup should go within the innermost scope, around the members that
236 should actually be added.
237 * If the module should not appear in the public API documentation, its
238 definition (\c \\defgroup) should be prefixed with a \c \\libinternal.
239 In this case, also all \c \\addtogroup commands for this module should be
240 similarly prefixed. Otherwise, they create the group in the public API
241 documentation, but without any of the content from the \c \\defgroup
242 definition. This may also cause the contents of the \c \\addtogroup section
243 to appear in the public API documentation, even if it otherwise would not.
245 Public API and library API groups
246 ---------------------------------
248 In addition to the module groups, two fixed groups are provided:
249 `group_publicapi` and `group_libraryapi`. Classes and files can be added to
250 these groups using \Gromacs specific custom \c \\inpublicapi and
251 \c \\inlibraryapi commands. The generated group documentation pages are not
252 very useful, but annotated classes and files show the API definition under the
253 name, making this information more easily accessible. These commands in
254 file-level comments are also used for some automatic intermodule dependency
255 validation (see below).
257 Note that functions, enumerations, and other entities that do not have a
258 separate page in the generated documentation can only belong to one group;
259 in such a case, the module group is preferred over the API group.
261 Automatic dependency checking
262 -----------------------------
264 The build system provides a `doc-check` target that automatically checks some
265 aspects of the documentation, as well as checking that header files are
266 actually used according to their API specifications (i.e., an internal headers
267 are not included from other modules). The checks depend on correct usage of
268 the commands listed above, in particular the visibility and API definitions in
269 file-level comments. These checks also provide some level of enforcement for
270 rules about dependencies between the modules, but currently the checks are not
273 The checker currently checks for a few different types of issues:
274 * For all Doxygen documentation (currently does not apply for members within
275 anonymous namespaces or members that do not appear in the documentation):
276 * If a member has documentation, it should have a brief description.
277 * A note is issued for in-body documentation for functions, since this is
278 ignored by our current settings.
279 * If a class has documentation, it should have public documentation only if
280 it appears in an installed header.
281 * If a class and its containing file has documentation, the class
282 documentation should not be visible if the file documentation is not.
284 * Consistent usage of
286 #include "..." // This should be used for Gromacs headers
290 #include <...> // This should be used for system and external headers
292 * Installed headers must not include non-installed headers, and must include
293 all other \Gromacs headers using relative paths so that they resolve
294 correctly also when installed.
295 * For documented files:
296 * Installed headers should have public documentation, and other files should
298 * The API level specified for a file should not be higher than where its
299 documentation is visible. For example, only publicly documented headers
300 should be specified as part of the public API.
301 * If an \c \\ingroup module_foo exists, it should match the subdirectory
302 that the file is actually part of in the file system.
303 * If a \c \\defgroup module_foo exists for the subdirectory where the file is,
304 the file should contain \c \\ingroup module_foo.
305 * Files should not include other files whose documentation visibility is
306 lower (if the included file is not documented, the check is skipped).
307 * For files that are part of documented modules
308 (\c \\defgroup module_foo exists for the subdirectory):
309 * Such files should not be included from outside their module if they are
310 undocumented or are not specified as part of library or public API.
312 The checker is based on extracting the Doxygen documentation in XML format.
313 This information is then read using a Python script, and combined with
314 information extracted from the file system and knowledge about the \Gromacs
315 source tree layout. The Python scripts are in the `doxygen/` folder.
316 In addition to printing the issues, they are also written into
317 `doxygen/doxygen-check.log` for later inspection.
319 The script is not currently perfect (either because of unfinished
320 implementation, or because Doxygen bugs or incompleteness of the Doxygen XML
321 output), and the current code also contains issues that the script detects, but
322 the authors have not fixed. To allow the script to still be used,
323 `doxygen/suppressions.txt` contains a list of issues that are filtered out from
324 the report. The syntax is simple:
328 where `<file>` is a path to the file that reports the message, and `<text>` is
329 the text reported. Both support `*` as a wildcard. If `<file>` is empty, the
330 suppression matches only messages that do not have an associated file.
331 `<file>` is matched against the trailing portion of the file name to make it
332 work even though the script reports absolute paths.
333 Empty lines and lines starting with `#` are ignored.
335 To add suppression for an issue, the line that reports the issue can be copied
336 into `suppressions.txt`, and the line number (if any) removed. If the
337 issue does not have a file name (or a pseudo-file) associated, a leading `:`
338 must be added. To cover many similar issues, parts of the line can then be
339 replaced with wildcards.
341 For some false positives from the script, the suppression mechanism is the
342 easiest way to silence the script, but otherwise the goal would be to minimize
343 the number of suppressions.
345 As a side effect, the XML extraction makes Doxygen parse all comments in the
346 code, even if they do not appear in the documentation. This can reveal latent
347 issues in the comments, like invalid Doxygen syntax. The messages from the XML
348 parsing are stored in `docs/doxygen/doxygen-xml.log` in the build tree, similar to
351 The `doc-check` target requires Python 2.7 (other versions may work, but have
354 Include dependency graphs
355 -------------------------
357 The build system also provides an `dep-graphs` target that generates include
358 dependency graphs with some additional annotations.
359 One graph is produced that shows all the modules under `src/gromacs/`, and
360 their include dependencies. Additionally, a file-level graph is produced for
361 each module, showing the include dependencies within that module. Currently,
362 these are mostly for eye candy, but they can also be used for analyzing
363 problematic dependencies to clean up the architecture.
364 The output is put in `doxygen/depgraphs/` in the build tree.
366 As with `doc-check`, Python 2.7 is required (other versions may work, but have
367 not been tested). To get `.png` versions of the graphs, `graphviz` is
368 additionally required.
372 The graph is written into `module-deps.dot.png`.
376 <dt>gray background</dt>
377 <dd>undocumented module</dd>
378 <dt>orange background</dt>
379 <dd>documented utility modules</dd>
380 <dt>red background</dt>
381 <dd>documented analysis modules</dd>
382 <dt>violet background</dt>
383 <dd>documented MD execution modules</dd>
384 <dt>light blue border</dt>
385 <dd>module contains public API (installed) headers</dd>
388 Edge colors (an edge with a certain color indicates that types above it in the
389 list are not present):
392 <dd>invalid dependency</dd>
394 <dd>legacy dependency
395 (dependency on undocumented file, or to undocumented directories)</dd>
397 <dd>public header depends on the other module</dd>
399 <dd>library header depends on the other module</dd>
401 <dd>source file depends on library header in the other module</dd>
402 <dt>dashed black</dt>
403 <dd>source file depends on public header in the other module</dd>
404 <dt>dashed green</dt>
405 <dd>test file depends on the other module</dd>
410 The graphs are written to <em>module_name</em>`-deps.dot.png`.
415 <dd>public API (installed) headers</dd>
417 <dd>library API headers</dd>
419 <dd>source files</dd>
426 Each edge signifies an include dependency; there is no additional information
429 Documenting specific code constructs
430 ====================================
432 This section describes the techical details and some tips and tricks for
433 documenting specific code constructs such that useful documentation is
434 produced. If you are wondering where to document a certain piece of
435 information, see the documentation structure section on \ref page_codelayout.
436 The focus of the documentation should be on the overview content: Doxygen pages
437 and the module documentation. An experienced developer can relatively easily
438 read and understand individual functions, but the documentation should help
439 in getting the big picture.
444 The pages that are accessible through navigation from the front page are
445 written using Markdown and are located under `docs/doxygen/`. Each page should be
446 placed in the page hierarchy by making it a subpage of another page, i.e., it
447 should be referenced once using \c \\subpage. `mainpage.md` is the root of the
450 If you need to exclude a page from the public API docs, you need to add it to
451 an exclude list in `Doxyfile-user.cmakein`, and ensure that there are no
452 references to the page from public API documentation. \c \\if `libapi` can be
453 used to add references in content that is otherwise public.
454 Generally, the pages should be on a high enough level and provide overview
455 content that is useful enough such that it is not necessary to exclude them
456 from the library API documentation.
461 For each module, decide on a header file that is the most important one for
462 that module (if there is no self-evident header, it may be better to designate,
463 e.g., module-doc.h for this purpose, but this is currently not done for any
464 module). This header should contain the \c \\defgroup definition for the
465 module. The name of the group should be `module_`<em>name</em>, where _name_
466 is the name of the subdirectory that hosts the module.
468 The module should be added to an appropriate group (see `docs/doxygen/misc.cpp` for
469 definitions) using \c \\ingroup to organize the "Modules" tab in the generated
472 One or more contact persons who know about the contents of the module should be
473 listed using \c \\author commands. This provides a point of contact if one
479 Classes and structs in header files appear always in Doxygen documentation,
480 even if their enclosing file is not documented. So start the documentation
481 blocks of classes that are not part of the public API with \c \\internal or
482 \c \\libinternal. Classes declared locally in source files or in unnamed
483 namespaces only appear in the full documentation.
485 If a whole class is not documented, this does not currently generate any
486 warning. The class is simply exluded from the documentation. But if a member
487 of a documented class is not documented, a warning is generated. Guidelines for
488 documenting free functions apply to methods of a class as well.
490 For base classes, the API classification (\c \\inpublicapi or
491 \c \\inlibraryapi) should be based on where the class is meant to be
492 subclassed. The visibility (\c \\internal or \c \\libinternal), in contrast,
493 should reflect the API classification of derived classes such that the base
494 class documentation is always generated together with the derived classes.
496 For classes that are meant to be subclassed and have protected members, the
497 protected members should only appear at the documentation level where the class
498 is meant to be subclassed. For example, if a class is meant to be subclassed
499 only within a module, the protected members should only appear in the
500 full documentation. This can be accomplished using \c \\cond (note that you
501 will need to add the \c \\cond command also to the source files to hide the
502 same methods from Doxygen, otherwise you will get confusing warnings).
504 Methods/functions/enums/macros
505 ------------------------------
507 These items do not appear in the documentation unless their enclosing scope is
508 documented. For class members, the scope is the class; otherwise, it is the
509 namespace if one exists, or the file. An \c \\addtogroup can also define a
510 scope if the group has higher visibility than the scope outside it.
511 So if a function is not within a namespace (mostly applicable to C code) and
512 has the same visibility as its enclosing file, it is not necessary to add a
513 \c \\internal or \c \\libinternal.
515 Static functions are currently extracted for all documentation flavors to allow
516 headers to declare `static inline` functions (used in, for example, math code).
517 Functions in anonymous namespaces are only extracted into the full
518 documentation. Together with the above rules, this means that you should avoid
519 putting a `static` function within a documented namespace, even within source
520 files, or it may inadvertently appear in the public API documentation.
522 If you want to exclude an item from the documentation, you need to put in
523 inside a \c \\cond block such that Doxygen does not see it.
524 Otherwise, a warning for an undocumented function is generated. You need to
525 enclose both the declaration and the definition with \c \\cond.
530 Each documented file should start with a documentation block (right after the
531 copyright notice) that documents the file. See the examples section for exact
532 formatting. Things to note:
533 * Please do not specify the file name explicitly after \c \\file. By default,
534 a file comment applies to the file it is contained in, and an explicit file
535 name only adds one more thing that can get out of date.
536 * \c \\brief cannot appear on the same line as the \c \\file, but should be on
538 * \c \\internal or \c \\libinternal should indicate where the header is visible.
539 As a general guideline, all installed headers should appear in the public API
540 documentation, i.e., not contain these commands. If nothing else, then to
541 document that it does not contain any public API functions. Headers that
542 declare anything in the library API should be marked with \c \\libinternal,
543 and the rest with \c \\internal.
544 * All source files, as well as most test files, should be documented with
545 \c \\internal, since they do not provide anything to public or library API,
546 and this avoids unintentionally extracting things from the file into those
547 documentations. Shared test files used in tests from other modules should be
548 marked with \c \\libinternal.
549 * \c \\inpublicapi or \c \\inlibraryapi should be used to indicate where the
550 header is meant to be directly included.
551 * As with files, one or more contact persons should be listed with \c \\author.
552 If you make significant modifications or additions to a file, consider adding
553 an \c \\author line for yourself.
558 Directory documentation does not typically contain useful information beyond a
559 possible brief description, since they correspond very closely to modules, and
560 the modules themselves are documented. A brief description is still useful to
561 provide a high-level overview of the source tree on the generated "Files" page.
562 A reference to the module is typically sufficient as a brief description for a
563 directory. All directories are currently documented in
564 `docs/doxygen/directories.cpp`.
573 Here is an example of documenting a C++ class and its containing header file.
574 Comments in the code and the actual documentation explain the used Doxygen
577 \includelineno doxygen-example.cpp
582 Here is another example of documenting a C header file (so avoiding all
583 C++-style comments), and including free functions. It also demonstrates the use
584 of \c \\addtogroup to add multiple functions into a module group without repeated
587 \includelineno doxygen-example.c
589 Scoping and visibility rules
590 ----------------------------
592 The rules where Doxygen expects something to be documented, and when are
593 commands like \c \\internal needed, can be complex. The examples below
594 describe some of the pitfalls.
596 \includelineno doxygen-example-scoping.cpp
601 Documenting a new module should place a comment like this in a central header
602 for the module, such that the "Modules" tab in the generated documentation can
603 be used to navigate to the module.
605 \includelineno doxygen-example-module.cpp
610 The most common mistake, in particular in C code, is to forget to document the
611 file. This causes Doxygen to ignore most comments in the file, so it
612 does not validate the contents of the comments either, nor is it possible to
613 actually check how the generated documentation looks like.
615 The following example shows some other common mistakes (and some less common)
616 that do not produce correct documentation, as well as Doxygen "features"/bugs
617 that can be confusing.
618 The issues are explained in normal comments above each code fragment.
620 \includelineno doxygen-example-issues.cpp
625 More examples you can find by looking at existing code in the source tree. In
626 particular new C++ code such as that in the `src/gromacs/analysisdata/` and
627 `src/gromacs/options/` subdirectories contains a large amount of code
628 documented mostly along these guidelines. Some comments in
629 `src/gromacs/selection/` (in particular, any C-like code) predate the
630 introduction of these guidelines, so those are not the best examples.