Foxww528

C++ Reference Material
Getting Started with Doxygen

What is doxygen?

Jul 29, 2008 Run doxygen in the shell prompt as doxygen Doxyfile (or with whatever file name you’ve chosen for the configuration file). Doxygen issues several messages before it finally produces the documentation in Hypertext Markup Language (HTML) and Latex formats (the default). A special documentation block is a C or C comment block with some additional markings, so doxygen knows it is a piece of documentation that needs to end up in the generated documentation. For each code item there are two types of descriptions, which together form the documentation: a brief description and detailed description, both are optional. Chocolatey is software management automation for Windows that wraps installers, executables, zips, and scripts into compiled packages. Chocolatey integrates w/SCCM, Puppet, Chef, etc. Chocolatey is trusted by businesses to manage software deployments.

If by any chance you already know what the javadoc tool does for you when writing Java programs, then the easiest way to describe doxygen in the current context is to say that doxygen is to C++ as javadoc is to Java.

Github Doxygen

If that analogy means nothing to you, then we should say that doxygen is a software utility that recognizes comments within C++ code that have a certain form, and uses them to produce a collection of HTML files containing the information in those comments. For this to be useful, of course, that information should be documentation for the surrounding source code, and this then allows the developer to place that documentation within the source code being documented. This in turn gives the developer much quicker access to the documentation and provides a greater incentive to keep the documentation up to date.

Some doxygen syntax

The first thing to note about the doxygen utility program is that it ignores C++ comments having either of the two usual forms(// ... or /* ... */).

But ... there are two kinds of special comments recognized (and processed) by doxygen:

1. Comments that start with a /** delimiter and end with a */ delimiter.
2. Comments that start with a /**< delimiter and end with a */ delimiter.

Here's the difference between the two: Use the first one if you want to place the comment before the thing you are commenting, but use the second one if you want to place the comment after the thing you are commenting.

The content of a comment having either of these syntactical forms might be just some text (one or two sentences describing whatever is being commented, for example), or some text like that plus some other text marked by special markers called tags, which we discuss below.

For example, here is a doxygen comment:

A doxygen tag is a keyword preceded by the @ symbol. Tags are used inside a doxygen comment to document special parts of the source code (such as a function return type or a function parameter), or to designate additional information (such as author and version number) that you wish to appear as part of the documentation. Text identified by tags is formatted in special ways by doxygen in its HTML output files.

Here is a list of some of the most frequently used doxygen tags:

The tags in the first column above are used for documenting an individual file, or a project, while those in the second column are used for documenting a function.

Some other useful doxygen notes:

1. The dash or hyphen (-) is used to denote a list item, which will be a bulleted item by default, but if you wish to have your list items automatically numbered, use -# instead.
2. Putting a period on a line by itself will terminate a list, if you line it up with the beginning of the list items in the list that you wish terminated. Each - or -# is placed in front of the item it identifies, is followed by a blank space, and is aligned with all the other similar items for the same list. Lists can also be nested. If a second list is nested inside a first list, the items in the second list should be indented with respect to the items in the first list.
3. Many ordinary HTML tags can also be used (<b></b> to make a word bold, for example).
4. The doxygen tool produces HTML files, and because of the way whitespace is treated in HTML you may from time to time have to 'force' line breaks in your HTML output files. You can do this in several ways, depending on the situation. Sometimes leaving a blank line in the input does the trick. You can also use the HTML <br> tag. Somewhat counter intuitively (if you are familiar with HTML), you can also use a n character in your doxygen comments.

An example

A short, and incomplete, example of doxygen documentation is provided in the source code of the sample file doxygen_example.cpp. For a more complete example, check out the documentation for the instructor-supplied utilities package as you continue to use it. You will also find some additional doxygen comments in some of the sample code used to illustrate our C++ programming style conventions under 'Rules + Guidelines: Coding Style'

In the short example given above, look for the above-mentioned doxygen comments and tags, as well as some HTML tags, and then study the corresponding HTML output to see the effect of each tag. This you can do by clicking on html which will take you to the index.html file in the html subdirectory produced from this program by the doxygen tool.

How to produce HTML documentation files from source code files containing doxygen comments

When the doxygen tool processes one or more input source code files, it produces, by default, in the current working directory, a subdirectory named html, which contains all the HTML files that document that source code, according to the doxygen comments contained in the source code. The starting point for browsing this documentation, as you might expect, is the file index.html.

For the above example, to produce the html directory and all the files in it, you just have to put the two files doxygen_example.cpp and the doxygen configuration file doxyconfig in the directory where you want the html directory to appear, and then enter this command:

The doxygen configuration file for any source code file or project can have any name you like. However, it will generally be convenient to give a configuration file for a given source code file or a given project a name that shows its connection with that file or project. If you look at the configuration file for the example you can easily see that for a different project you will want to change the values of PROJECT_NAME, PROJECT_NUMBER and INPUT, but you can probably leave the other parameter values set as they are. Note that INPUT contains a whitespace separated list of all files that you want doxygen to process.

On-Line References

1. Doxygen home page You may get all the detailed information you need, as well as the latest version of doxygen itself from this site.
2. You also have a very good example of doxygen at work in the HTML documentation for the C++ utilities package. You should know where that is and be referring to it frequently!

Doxygen is a documentation generation tool (see http://www.doxygen.org).This module looks for Doxygen and some optional tools it supports:

Graphvizdot utility used to render variousgraphs.

Message Chart Generator utility usedby Doxygen's msc and mscfile commands.

Dia the diagram editor used by Doxygen'sdiafile command.

New in version 3.9: These tools are available as components in the find_package() command.For example:

The following variables are defined by this module:

True if the doxygen executable was found.

The version reported by doxygen--version.

New in version 3.9: The module defines IMPORTED targets for Doxygen and each component found.These can be used as part of custom commands, etc. and should be preferred overold-style (and now deprecated) variables like DOXYGEN_EXECUTABLE. Thefollowing import targets are defined if their corresponding executable could befound (the component import targets will only be defined if that component wasrequested):

Functions¶

This function is intended as a convenience for adding a target for generatingdocumentation with Doxygen. It aims to provide sensible defaults so thatprojects can generally just provide the input files and directories and thatwill be sufficient to give sensible results. The function supports theability to customize the Doxygen configuration used to build thedocumentation.

The function constructs a Doxyfile and defines a custom target that runsDoxygen on that generated file. The listed files and directories are used asthe INPUT of the generated Doxyfile and they can contain wildcards.Any files that are listed explicitly will also be added as SOURCES of thecustom target so they will show up in an IDE project's source list.

So that relative input paths work as expected, by default the workingdirectory of the Doxygen command will be the current source directory (i.e.CMAKE_CURRENT_SOURCE_DIR). This can be overridden with theWORKING_DIRECTORY option to change the directory used as the relativebase point. Note also that Doxygen's default behavior is to strip the workingdirectory from relative paths in the generated documentation (see theSTRIP_FROM_PATHDoxygen config option for details).

If provided, the optional comment will be passed as the COMMENT forthe add_custom_target() command used to create the custom targetinternally.

New in version 3.12: If ALL is set, the target will be added to the default build target.

New in version 3.16: If USE_STAMP_FILE is set, the custom command defined by this function willcreate a stamp file with the name <targetName>.stamp in the currentbinary directory whenever doxygen is re-run. With this option present, allitems in <filesOrDirs> must be files (i.e. no directories, symlinks orwildcards) and each of the files must exist at the timedoxygen_add_docs() is called. An error will be raised if any of theitems listed is missing or is not a file when USE_STAMP_FILE is given.A dependency will be created on each of the files so that doxygen will onlybe re-run if one of the files is updated. Without the USE_STAMP_FILEoption, doxygen will always be re-run if the <targetName> target is builtregardless of whether anything listed in <filesOrDirs> has changed.

The contents of the generated Doxyfile can be customized by setting CMakevariables before calling doxygen_add_docs(). Any variable with a name ofthe form DOXYGEN_<tag> will have its value substituted for thecorresponding <tag> configuration option in the Doxyfile. See theDoxygen documentation for thefull list of supported configuration options.

Some of Doxygen's defaults are overridden to provide more appropriatebehavior for a CMake project. Each of the following will be explicitly setunless the variable already has a value before doxygen_add_docs() iscalled (with some exceptions noted):

Set to YES if the dot component was requested and it was found,NO otherwise. Any existing value of DOXYGEN_HAVE_DOT is ignored.

Doxygen Tags

Set to YES by this module (note that this requires a dot versionnewer than 1.8.10). This option is only meaningful if DOXYGEN_HAVE_DOTis also set to YES.

Set to NO by this module.

For Visual Studio based generators, this is set to the form recognized bythe Visual Studio IDE: $file($line):$text. For all other generators,Doxygen's default value is not overridden.

Populated with the name of the current project (i.e.PROJECT_NAME).

Populated with the version of the current project (i.e.PROJECT_VERSION).

Populated with the description of the current project (i.e.PROJECT_DESCRIPTION).

Projects should not set this variable. It will be populated with the set offiles and directories passed to doxygen_add_docs(), thereby providingconsistent behavior with the other built-in commands likeadd_executable(), add_library() andadd_custom_target(). If a variable named DOXYGEN_INPUT is setby the project, it will be ignored and a warning will be issued.

Set to YES by this module.

If the set of inputs includes directories, this variable will specifypatterns used to exclude files from them. The following patterns are addedby doxygen_add_docs() to ensure CMake-specific files and directoriesare not included in the input. If the project setsDOXYGEN_EXCLUDE_PATTERNS, those contents are merged with theseadditional patterns rather than replacing them:

Set to CMAKE_CURRENT_BINARY_DIR by this module. Note that ifthe project provides its own value for this and it is a relative path, itwill be converted to an absolute path relative to the current binarydirectory. This is necessary because doxygen will normally be run from adirectory within the source tree so that relative source paths work asexpected. If this directory does not exist, it will be recursively createdprior to executing the doxygen commands.

Doxygen Code Example

To change any of these defaults or override any other Doxygen config option,set relevant variables before calling doxygen_add_docs(). For example:

A number of Doxygen config options accept lists of values, but Doxygen requiresthem to be separated by whitespace. CMake variables hold lists as a string withitems separated by semi-colons, so a conversion needs to be performed. Thedoxygen_add_docs() command specifically checks the following Doxygen configoptions and will convert their associated CMake variable's contents into therequired form if set.

The following single value Doxygen options will be quoted automaticallyif they contain at least one space:

New in version 3.11: There are situations where it may be undesirable for a particular config optionto be automatically quoted by doxygen_add_docs(), such as ALIASES whichmay need to include its own embedded quoting. The DOXYGEN_VERBATIM_VARSvariable can be used to specify a list of Doxygen variables (including theleading DOXYGEN_ prefix) which should not be quoted. The project is thenresponsible for ensuring that those variables' values make sense when placeddirectly in the Doxygen input file. In the case of list variables, list itemsare still separated by spaces, it is only the automatic quoting that isskipped. For example, the following allows doxygen_add_docs() to applyquoting to DOXYGEN_PROJECT_BRIEF, but not each item in theDOXYGEN_ALIASES list (bracket syntax can alsobe used to make working with embedded quotes easier):

The resultant Doxyfile will contain the following lines:

Deprecated Result Variables¶

For compatibility with previous versions of CMake, the following variablesare also defined but they are deprecated and should no longer be used:

The path to the doxygen command. If projects need to refer to thedoxygen executable directly, they should use the Doxygen::doxygenimport target instead.

True if the dot executable was found.

Doxygen Example

The path to the dot command. If projects need to refer to the dotexecutable directly, they should use the Doxygen::dot import targetinstead.

Doxygen.org

Doxygen

The path to the directory containing the dot executable as reported inDOXYGEN_DOT_EXECUTABLE. The path may have forward slashes even on Windowsand is not suitable for direct substitution into a Doxyfile.in template.If you need this value, get the IMPORTED_LOCATION property of theDoxygen::dot target and use get_filename_component() to extractthe directory part of that path. You may also want to consider usingfile(TO_NATIVE_PATH) to prepare the path for a Doxygenconfiguration file.

Deprecated Hint Variables¶

This variable has no effect for the component form of find_package.In backward compatibility mode (i.e. without components list) it preventsthe finder module from searching for Graphviz's dot utility.