Formatting Comments for Doxygen
The ROOT team has adopted Doxygen for generating the Reference Guide. Here you will find a number of conventions and tips to be used in source code to generate proper documentation.
How to generate the doxygen documentation
Developers may generate the documentation by hand to see the results of the current changes before committing them to the repository. The automatic daily Jenkins procedures will generate the complete set of documentation.
The results are placed by default at ${HOME}/rootdoc/html
.
The script $ROOTSYS/documentation/doxygen/makeinput.sh
defines the INPUT
tag in Doxyfile
.
It can be edited to reduce the number of input files and thus reduce the time for generating
the HTML pages. Typically you will keep only the folder(s) in which the documentation you are
working on is. To see the result of this local build you should open, in your preferred web
browser, the file ${HOME}/rootdoc/html/index.html
.
Compilation prerequisites on Ubuntu
- apt install doxygen make jupyter-nbconvert
- pip install scandir nbformat metakernel ipykernel
- Optional: apt install qhelpgenerator-qt5. In case of older Ubuntu versions, use qt4-dev-tools instead, and modify in the Doxyfile QHG_LOCATION to /usr/lib/x86_64-linux-gnu/qt4/bin/qhelpgenerator
General Guidelines
Classes and methods can be documented both in the .cxx and .h files. For the long descriptions of a class functionality and its methods we usually prefer the .cxx file.
Class documentation
The documentation for the class is in general located at the beginning of the .cxx file.
The \class
Doxygen command is mandatory otherwise Doxygen will not associate the comments
to the proper class. The first sentence is a brief description of the class and will
appear in all class listings. For an example see the TF2 class documentation:
Method documentation
Methods are documented just before the method/function is defined in the .cxx file.
The use of \param[in]
and \param[out]
is encouraged to document the parameters of the
method. The agreed formatting is as follows:
Free functions documentation
Doxygen does not document default parameters of free functions if the only doxygen documentation provided for the function is in source files (as opposed to header files). To bypass this issue it is enough to provide a brief documentation for such functions in the header file. For example if the source file is:
and the header file:
Then a proper documentation with the default parameters is generated.
Data Member documentation
IMPORTANT: It is crucial to use ///<
and only ///<
to comment data members: this
comment is correctly understood by genreflex/rootcling.
The usage of other Doxygen constructs can interfere with the I/O subsystem!
The usage of “//!” will still result in transiency of members but not in Doxygen documentation.
Tutorials’ documentation
ROOT tutorials are also included in the ROOT documentation. The tutorials’ macros headers should look like:
This example shows that four new directives have been implemented:
-
\macro_image
The images produced by this macro are shown. A caption can be added to document the pictures:\macro_image This is a picture
. When the option(nobatch)
is passed, the macro is executed without the batch option. Some tutorials generate pictures (png or pdf) withPrint
orSaveAs
. Such pictures can be displayed with\macro_image (picture_name.png[.pdf])
When the option (tcanvas_js) is used the image is displayed as JavaScript. For ROOT 7 tutorials, when the option (rcanvas_js) is used the image is displayed as json file. -
\macro_code
The macro code is shown. A caption can be added:\macro_code This is code
-
\macro_output
The output produced by this macro is shown. A caption can be added:\macro_output This the macro output
-
\notebook
To generate the corresponding jupyter notebook. In case the tutorial does not generate any graphics output, the option-nodraw
should be added. This directive needs jupyter to be properly installed when building the documentation of tutorials having this directive.
Note that the doxygen directive \authors
or \author
must be the last one
of the macro header.
Useful tips for common documentation artifacts
A couple of useful online web tools for the conversion and formatting:
Code blocks
Simple code blocks are documented by indenting the code 4 spaces.
Longer code blocks can done with fenced lines consisting of 3 or more tilde (~) characters on a line. The end of the block should have the same number of tildes. Here is an example (note that tildes should start on first column!):
Macros and generated figures
The keywords Begin_Macro
and End_Macro
are understood by the filter command to extract the code and produce the figure that will be inserted automatically in place. If in addition one wants to show the macro’s code the parameter source
should added to the Begin_Macro
directive: Begin_Macro(source)
. The code enclosed by Begin_Macro
and End_Macro
can be plain C++ code:
or a file name containing the code to be executed:
Begin_Macro
also accept the image file type as option. "png"
or "svg"
.
"png"
is the default value. For example: Begin_Macro(source, svg)
will show
the code of the macro and the image will be is svg format. The "width"
keyword
can be added to define the width of the picture in pixel: "width=400"
will
scale a picture to 400 pixel width. This allow to define large pictures which
can then be scaled down to have a better definition.
Images
Images should be placed in in directory documentation/doxygen/images
with the name <class>_<figurename>.png
. They are referenced in the comments with the \image
doxygen command:
Formulas
In paragraph formulas can be added with \f$
, for example \f$ \frac{1}{1 - x}\f$
. Column centered and multi-line formulas can be added with the commands \f[ ... \f]
or \f{...}{ ...\f}
. See the following examples:
Tables
Markdown tables are very convening for tabulated documentation. See the following example:
Grouping classes in modules
You can group the classes according to the corresponding packages (e.g. math, hist, tree, etc…). In order to do this, you need to define first somewhere, as a code comment or in a separate page a
group using the \defgroup
tag.
Example
Then one needs to add in the class description comments the \ingroup
tag. For example in the class TH1, which is part of the Hist group one should add
Include additional documentation pages in HTML or Markdown format
One can add extra pages for the documentation in HTML or Markdown format (preferable) in the package/doc directory (e.g. hist/doc). These page could be used to
provide a general documentation of the package. The pages should be included in a file with name as the package name and the .md or .html suffix (e.g. hist.md).
The file should contain, in addition to the package description, the Doxygen command \page [name] [title]
which defines the internal page name (used to reference that page) and
the page title.
For example:
Inside page you can reference to groups or other pages using the Doxygen commands \subpage [refname] ["text"]
and \ref [refname] ["text"]
.
See as example the existing math/doc/Math.md
file.