+Using Doxygen {#page_doxygen}
+=============
+
+This page documents how Doxygen is set up in the \Gromacs source tree,
+as well as guidelines for adding new Doxygen comments. Examples are included,
+as well as tips and tricks for avoiding Doxygen warnings. The guidelines focus
+on C++ code and other new code that follows the new module layout.
+Parts of the guidelines are still applicable to documenting older code (e.g.,
+within `gmxlib/` or `mdlib/`), in particular the guidelines about formatting
+the Doxygen comments and the use of \c \\internal.
+\ref page_codelayout documents the overall structure of the documentation.
+
+To get started quickly, you only need to read the first two sections to
+understand the overall structure of the documentation, and take a look at the
+examples at the end. The remaining sections provide the details for
+understanding why the examples are the way they are, and for more complex
+situations. They are meant more as a reference to look up solutions for
+particular problems, rather than single-time reading. To understand or find
+individual Doxygen commands, you should first look at Doxygen documentation
+(http://www.stack.nl/~dimitri/doxygen/manual/index.html).
+
+
+Documentation flavors
+=====================
+The \Gromacs source tree is set up to produce three different levels of Doxygen
+documentation:
+
+1. Public API documentation (suffix `-user`), which documents functions and
+ classes exported from the library and intended for use outside the \Gromacs
+ library.
+2. Library API documentation (suffix `-lib`), which additionally includes
+ functions and classes that are designed to be used from other parts of
+ \Gromacs, as well as some guidelines that are mostly of interest to
+ developers.
+3. Full documentation (suffix `-full`), which includes (nearly) all (documented)
+ functions and classes in the source tree.
+
+Each subsequent level of documentation includes all the documentation from the
+levels above it. The suffixes above refer to the suffixes of Doxygen input and
+output files, as well as the name of the output directory. When all the
+flavors have been built, the front pages of the documentation contain links to
+the other flavors, and explain the differences in more detail.
+
+As a general guideline, the public API documentation should be kept free of
+anything that a user linking against an unmodified \Gromacs does not see.
+In other words, the public API documentation should mainly document the
+contents of installed headers, and provide the necessary overview of using
+those. Also, verbosity requirements for the public API documentation are
+higher: ideally, readers of the documentation could immediately start using the
+API based on the documentation, without any need to look at the implementation.
+
+Similarly, the library API documentation should not contain things that other
+modules in \Gromacs can or should never call. In particular, anything declared
+locally in source files should be only available in the full documentation.
+Also, if something is documented, and is not identified to be in the library
+API, then it should not be necessary to call that function from outside its
+module.
+
+
+Building the documentation
+==========================
+
+If you simply want to see up-to-date documentation, you can go to
+http://jenkins.gromacs.org/job/Doxygen_Nightly_master/javadoc/html-lib/index.xhtml
+to see the documentation for the current development version.
+Jenkins also runs Doxygen for all changes pushed to Gerrit for master, and the
+resulting documentation can be viewed from the link posted by Jenkins. The
+Doxygen build is marked as unstable if it introduces any Doxygen warnings.
+
+You may need to build the documentation locally if you want to check the
+results after adding/modifying a significant amount of comments. This is
+recommended in particular if you do not have much experience with Doxygen.
+It is a good idea to build with all the different settings to see that the
+result is what you want, and that you do not produce any warnings.
+For local work, it is generally a good idea to set `GMX_COMPACT_DOXYGEN=ON`
+CMake option, which removes some large generated graphs from the documentation
+and speeds up the process significantly.
+
+All files related to Doxygen reside in the `doxygen/` subdirectory in the source
+and build trees. In a freshly checked out source tree, this directory contains
+various `Doxyfile-*.cmakein` files. When you run CMake, corresponding files
+`Doxyfile-user`, `Doxyfile-lib`, and `Doxyfile-full` are generated at the
+corresponding location in the build tree. There is also a
+`Doxyfile-common.cmakein`, which is used to produce `Doxyfile-common`.
+This file contains settings that are shared between all the input files.
+`Doxyfile-compact` provides the extra settings for `GMX_COMPACT_DOXYGEN=ON`.
+
+You can run Doxygen directly with one of the generated files (all output will
+be produced under the current working directory), or build one of the
+`doc-user`, `doc-lib`, and `doc-full` targets. The targets run Doxygen in a
+quieter mode and only show the warnings if there were any, and put the output
+under `doxygen/` in the build tree. The `doc-all` target builds all three
+targets with less typing.
+
+The generated documentation is put under `html-user/`, `html-lib/`, and/or
+`html-full/` in the output directory. Open `index.xhtml` file from one of
+these subdirectories to start browsing (for \Gromacs developers, the
+`html-lib/` is a reasonable starting point). Log files with all Doxygen
+warnings are also produced as `doxygen-*.log`, so you can inspect them after
+the run.
+
+You will need Doxygen 1.8.5 to build the current documentation. Other versions
+may work, but likely also produce warnings. Additionally,
+[graphviz](http://www.graphviz.org) and
+[mscgen](http://www.mcternan.me.uk/mscgen/) are required for some graphs in
+the documentation, and `latex` for formulas. Working versions are likely
+available through most package managers. It is possible to build the
+documentation without these tools, but you will see some errors and the related
+figures will be missing from the documentation.
+
+
+General guidelines for Doxygen markup
+=====================================
+
+Doxygen provides quite a few different alternative styles for documenting the
+source code. There are subtleties in how Doxygen treats the different types of
+comments, and this also depends somewhat on the Doxygen configuration. It is
+possible to change the meaning of a comment by just changing the style of
+comment it is enclosed in. To avoid such issues, and to avoid needing to
+manage all the alternatives, a single style throughout the source tree is
+preferable. When it comes to treatment of styles, \Gromacs uses the default
+Doxygen configuration with one exception: `JAVADOC_AUTOBRIEF` is set ON to
+allow more convenient one-line brief descriptions in C code.
+
+Majority of existing comments in \Gromacs uses Qt-style comments (`/*!` and
+`//!` instead of `/*``*` and `///`, \c \\brief instead of \c \@brief etc.),
+so these should be used also for new documentation. There is a single
+exception for brief comments in C code; see below.
+
+Similarly, existing comments use `/*!` for multiline comments in both C and
+C++ code, instead of using multiple `//!` lines for C++. The rationale is that
+since the code will be a mixture of both languages for a long time, it is more
+uniform to use similar style in both. Also, since files will likely transition
+from C to C++ gradually, rewriting the comments because of different style
+issues should not generally be necessary. Finally, multi-line `//!` comments
+can work differently depending on Doxygen configuration, so it is better to
+avoid that ambiguity.
+
+When adding comments, ensure that a short brief description is always produced.
+This is used in various listings, and should briefly explain the purpose of the
+method without unnecessarily expanding those lists.
+The basic guideline is to start all comment blocks with \c \\brief (possibly
+after some other Doxygen commands).
+If you want to avoid the \c \\brief for one-liners, you can use `//!`, but the
+description must fit on a single line; otherwise, it is not interpreted as a
+brief comment. Note in particular that a simple `/*!` without a \c \\brief
+does not produce a brief description.
+Also note that \c \\brief marks the whole following paragraph as a brief
+description, so you should insert an empty line after the intended brief
+description.
+
+In C code, `//` comments must be avoided because some compilers do not like
+them. If you want to avoid the \c \\brief for one-liners in C code, use
+`/*``*` instead of `//!`. If you do this, the brief description should not
+contain unescaped periods except at the end. Because of this, you should
+prefer `//!` in C++ code.
+
+Put the documentation comments in the header file that contains the
+declaration, if such a header exists.
+Implementation-specific comments that do not influence how a method
+is used can go into the source file, just before the method definition, with an
+\c \\internal tag in the beginning of the comment block. Doxygen-style comments
+within functions are not generally usable.
+
+At times, you may need to exclude some part of a header or a source file such
+that Doxygen does not see it at all. In general, you should try to avoid this,
+but it may be necessary to remove some functions that you do not want to appear
+in the public API documentation, and which would generate warnings if left
+undocumented, or to avoid Doxygen warnings from code it does not understand.
+Prefer \c \\cond and \c \\endcond to do this. If \c \\cond does not work for
+you, you can also use \c \#ifndef `DOXYGEN`. If you exclude a class method in
+a header, you also need to exclude it in the source code to avoid warnings.
+
+
+\Gromacs specifics
+=================
+
+The general guidelines on the style of Doxygen comments were given above.
+This section introduces \Gromacs specific constructs currently used in Doxygen
+documentation, as well as how \Gromacs uses Doxygen groups to organize the
+documentation.
+
+Controlling documentation visibility
+------------------------------------
+
+To control in which level of documentation a certain function appears, three
+different mechanisms are used:
+* Global Doxygen configuration. This is mainly used to include
+ declarations local to source files only in the full documentation.
+ You can find the details from the `Doxyfile-*.cmakein` files, and some of
+ them are also mentioned below on individual code constructs.
+* The standard Doxygen commands \c \\internal and \c \\endinternal mark the
+ documentation to be only extracted into the full documentation
+ (`INTERNAL_DOCS` is `ON` only for the full documentation).
+ In addition, \Gromacs specific custom Doxygen commands \c \\libinternal and
+ \c \\endlibinternal are provided, which only exclude the documentation from
+ the public API documentation. These are implemented by expanding the
+ commands to either \c \\internal or to a no-op, depending on the
+ documentation level.
+* Doxygen commands \c \\if and \c \\cond can be used with section names
+ `libapi` and `internal` to only include the documentation in library API and
+ the full documentation, respectively. `libapi` is also defined in the full
+ documentation. These are declared using `ENABLED_SECTIONS` in the Doxygen
+ configuration files.
+
+Examples of locations where it is necessary to use these explicit commands are
+given below in the sections on individual code constructs.
+
+Modules as Doxygen groups
+-------------------------
+
+As described in \ref page_codelayout, each subdirectory under `src/gromacs/`
+represents a _module_, i.e., a somewhat coherent collection of routines.
+Doxygen cannot automatically generate a list of routines in a module; it only
+extracts various alphabetical indexes that contain more or less all documented
+functions and classes. To help reading the documentation, the routines for a
+module should be visible in one place.
+
+\Gromacs uses Doxygen groups to achieve this: for each documented module, there
+is a \c \\defgroup definition for the module, and all the relevant classes and
+functions need to be manually added to this group using \c \\ingroup and
+\c \\addtogroup.
+The group page also provides a natural place for overview documentation about
+the module, and can be navigated to directly from the "Modules" tab in the
+generated documentation.
+
+Public API and library API groups
+---------------------------------
+
+In addition to the module groups, two fixed groups are provided:
+`group_publicapi` and `group_libraryapi`. Classes and files can be added to
+these groups using \Gromacs specific custom \c \\inpublicapi and
+\c \\inlibraryapi commands. The generated group documentation pages are not
+very useful, but annotated classes and files show the API definition under the
+name, making this information more easily accessible. These commands in
+file-level comments are also used for some automatic intermodule dependency
+validation (see below).
+
+Note that functions, enumerations, and other entities that do not have a
+separate page in the generated documentation can only belong to one group;
+in such a case, the module group is preferred over the API group.
+
+Automatic dependency checking
+-----------------------------
+
+The build system provides three targets, `depcheck`, `doccheck`, and
+`depgraphs`, that depend on correct usage of the above commands, in particular
+the visibility and API definitions in file-level comments.
+These checks also provide some level of enforcement for rules about
+dependencies between the modules, but currently the checks are not run
+automatically.
+
+The `depcheck` target checks for issues that either completely or subtly break
+the installed headers: an installed header including a non-installed header, or
+an installed header installing another header using a path that does not
+resolve correctly when the headers are installed. It also checks for
+consistent usage of
+\code
+#include "..." // This should be used for Gromacs headers
+\endcode
+versus
+\code
+#include <...> // This should be used for system and external headers.
+\endcode
+
+The `doccheck` target additionally checks that if an included file is
+documented, it is not used against the API definition specified in the
+file-level comment. For example, including a file without any API definition
+from another module produces an error. Another example of a check is that a
+non-installed header with public documentation triggers an error.
+
+The `depgraphs` target generates include dependency graphs. One graph is
+produced that shows all the modules under `src/gromacs/`, and their include
+dependencies. Additionally, a file-level graph is produced for each module,
+showing the include dependencies within that module. Currently, these are
+mostly for eye candy, but they can also be used for analyzing problematic
+dependencies to clean up the architecture. A legend for the graphs is
+currently included as comments in `admin/includedeps.py`. The output is put in
+`doxygen/depgraphs/`.
+
+These targets require Python 2.7; the graph generation additionally requires
+`graphviz`.
+
+
+Documenting specific code constructs
+====================================
+
+This section describes the techical details and some tips and tricks for
+documenting specific code constructs such that useful documentation is
+produced. If you are wondering where to document a certain piece of
+information, see the documentation structure section on \ref page_codelayout.
+The focus of the documentation should be on the overview content: Doxygen pages
+and the module documentation. An experienced developer can relatively easily
+read and understand individual functions, but the documentation should help
+in getting the big picture.
+
+Doxygen pages
+-------------
+
+The pages that are accessible through navigation from the front page are
+written using Markdown and are located under `doxygen/`. Each page should be
+placed in the page hierarchy by making it a subpage of another page, i.e., it
+should be referenced once using \c \\subpage. `mainpage.md` is the root of the
+hierarchy.
+
+If you need to exclude a page from the public API docs, you need to add it to
+an exclude list in `Doxyfile-user.cmakein`, and ensure that there are no
+references to the page from public API documentation. \c \\if `libapi` can be
+used to add references in content that is otherwise public.
+Generally, the pages should be on a high enough level and provide overview
+content that is useful enough such that it is not necessary to exclude them
+from the library API documentation.
+
+Modules
+-------
+
+For each module, decide on a header file that is the most important one for
+that module (if there is no self-evident header, it may be better to designate,
+e.g., module-doc.h for this purpose, but this is currently not done for any
+module). This header should contain the \c \\defgroup definition for the
+module. The name of the group should be `module_`<em>name</em>, where _name_
+is the name of the subdirectory that hosts the module.
+
+The module should be added to an appropriate group (see `doxygen/misc.cpp` for
+definitions) using \c \\ingroup to organize the "Modules" tab in the generated
+documentation.
+
+One or more contact persons who know about the contents of the module should be
+listed using \c \\author commands. This provides a point of contact if one
+has questions.
+
+Classes/structs
+---------------
+
+Classes and structs in header files appear always in Doxygen documentation,
+even if their enclosing file is not documented. So start the documentation
+blocks of classes that are not part of the public API with \c \\internal or
+\c \\libinternal. Classes declared locally in source files or in unnamed
+namespaces only appear in the full documentation.
+
+If a whole class is not documented, this does not currently generate any
+warning. The class is simply exluded from the documentation. But if a member
+of a documented class is not documented, a warning is generated. Guidelines for
+documenting free functions apply to methods of a class as well.
+
+For base classes, the API classification (\c \\inpublicapi or
+\c \\inlibraryapi) should be based on where the class is meant to be
+subclassed. The visibility (\c \\internal or \c \\libinternal), in contrast,
+should reflect the API classification of derived classes such that the base
+class documentation is always generated together with the derived classes.
+
+For classes that are meant to be subclassed and have protected members, the
+protected members should only appear at the documentation level where the class
+is meant to be subclassed. For example, if a class is meant to be subclassed
+only within a module, the protected members should only appear in the
+full documentation. This can be accomplished using \c \\cond (note that you
+will need to add the \c \\cond command also to the source files to hide the
+same methods from Doxygen, otherwise you will get confusing warnings).
+
+Methods/functions/enums/macros
+------------------------------
+
+These items do not appear in the documentation unless their enclosing scope is
+documented. For class members, the scope is the class; otherwise, it is the
+namespace if one exists, or the file. An \c \\addtogroup can also define a
+scope if the group has higher visibility than the scope outside it.
+So if a function is not within a namespace (mostly applicable to C code) and
+has the same visibility as its enclosing file, it is not necessary to add a
+\c \\internal or \c \\libinternal.
+
+Static functions are currently extracted for all documentation flavors to allow
+headers to declare `static inline` functions (used in, for example, math code).
+Functions in anonymous namespaces are only extracted into the full
+documentation. Together with the above rules, this means that you should avoid
+putting a `static` function within a documented namespace, even within source
+files, or it may inadvertently appear in the public API documentation.
+
+If you want to exclude an item from the documentation, you need to put in
+inside a \c \\cond block such that Doxygen does not see it.
+Otherwise, a warning for an undocumented function is generated. You need to
+enclose both the declaration and the definition with \c \\cond.
+
+Files
+-----
+
+Each documented file should start with a documentation block (right after the
+copyright notice) that documents the file. See the examples section for exact
+formatting. Things to note:
+* Please do not specify the file name explicitly after \c \\file. By default,
+ a file comment applies to the file it is contained in, and an explicit file
+ name only adds one more thing that can get out of date.
+* \c \\brief cannot appear on the same line as the \c \\file, but should be on
+ the next line.
+* \c \\internal or \c \\libinternal should indicate where the header is visible.
+ As a general guideline, all installed headers should appear in the public API
+ documentation, i.e., not contain these commands. If nothing else, then to
+ document that it does not contain any public API functions. Headers that
+ declare anything in the library API should be marked with \c \\libinternal,
+ and the rest with \c \\internal.
+* All source files, as well as most test files, should be documented with
+ \c \\internal, since they do not provide anything to public or library API,
+ and this avoids unintentionally extracting things from the file into those
+ documentations. Shared test files used in tests from other modules should be
+ marked with \c \\libinternal.
+* \c \\inpublicapi or \c \\inlibraryapi should be used to indicate where the
+ header is meant to be directly included.
+* As with files, one or more contact persons should be listed with \c \\author.
+ If you make significant modifications or additions to a file, consider adding
+ an \c \\author line for yourself.
+
+Directories
+-----------
+
+Directory documentation does not typically contain useful information beyond a
+possible brief description, since they correspond very closely to modules, and
+the modules themselves are documented. A brief description is still useful to
+provide a high-level overview of the source tree on the generated "Files" page.
+A reference to the module is typically sufficient as a brief description for a
+directory. All directories are currently documented in
+`doxygen/directories.cpp`.
+
+
+Examples
+========
+
+Basic C++
+---------
+
+Here is an example of documenting a C++ class and its containing header file.
+Comments in the code and the actual documentation explain the used Doxygen
+constructs.
+
+\includelineno doxygen-example.cpp
+
+Basic C
+-------
+
+Here is another example of documenting a C header file (so avoiding all
+C++-style comments), and including free functions. It also demonstrates the use
+of \c \\addtogroup to add multiple functions into a module group without repeated
+\c \\ingroup tags.
+
+\includelineno doxygen-example.c
+
+Scoping and visibility rules
+----------------------------
+
+The rules where Doxygen expects something to be documented, and when are
+commands like \c \\internal needed, can be complex. The examples below
+describe some of the pitfalls.
+
+\includelineno doxygen-example-scoping.cpp
+
+Module documentation
+--------------------
+
+Documenting a new module should place a comment like this in a central header
+for the module, such that the "Modules" tab in the generated documentation can
+be used to navigate to the module.
+
+\includelineno doxygen-example-module.cpp
+
+Common mistakes
+---------------
+
+The most common mistake, in particular in C code, is to forget to document the
+file. This causes Doxygen to ignore most of the comments in the file, so it
+does not validate the contents of the comments either, nor is it possible to
+actually check how the generated documentation looks like.
+
+The following example shows some other common mistakes that do not produce
+correct documentation. The issues are explained in normal comments above each
+code fragment.
+
+\includelineno doxygen-example-issues.cpp
+
+Existing code
+-------------
+
+More examples you can find by looking at existing code in the source tree. In
+particular new C++ code such as that in the `src/gromacs/analysisdata/` and
+`src/gromacs/options/` subdirectories contains a large amount of code
+documented mostly along these guidelines. Some comments in
+`src/gromacs/selection/` (in particular, any C-like code) predate the
+introduction of these guidelines, so those are not the best examples.
biod.pnpi.spb.ru / alexxy / gromacs.git / commitdiff