Doxygen-style comments are used to provide documentation in-line with the OpenOCD source code.

These comments are used to document functions, variables, structs, enums, fields, and everything else that might need to be documented for developers. Additional files containing comments that supplement the code comments in order to provide complete developer documentation.

Even if you already know Doxygen, please read this Primer to learn how OpenOCD developers already use Doxygen features in the project tree. For more information about OpenOCD's required style for using Doxygen, see the Doxygen Style Guide page and look at existing documentation in the doc/manual tree.

Doxygen Input Files

Doxygen has been configured parse all of the C source code files (*.c and *.h) in src/ in order to produce a complete reference of all OpenOCD project symbols. In addition to the source code files, other files will also be scanned for comment blocks; some are referenced explicitly by the INPUT variable in the Doxygen configuration file.

By default, the Doxygen configuration enables a "full" set of features, including generation of dependency graphs (using the GraphViz package). These features may be disabled by editing the Doxyfile.in file at the top of the project tree; the configuration file includes comments that provide detailed documentation for each option.

To support out-of-tree building of the documentation, the Doxyfile.in INPUT values will have all instances of the string "@srcdir@" replaced with the current value of the make variable . The Makefile uses a rule to convert Doxyfile.in into the Doxyfile used by make doxygen.

OpenOCD Input Files

OpenOCD uses the INPUT mechanism to include additional documentation to provide The Manual for OpenOCD Developers. These extra files contain high-level information intended to supplement the relatively low-level documentation that gets extracted from the source code comments.

OpenOCD's Doxygen configuration file will search for all .txt files that can be found under the doc/manual directory in the project tree. New files containing valid Doxygen markup that are placed in or under that directory will be detected and included in The Manual automatically.

Doxygen Reference Manual

The full documentation for Doxygen can be referenced on-line at the project home page: http://www.doxygen.org/index.html. In HTML versions of this document, an image with a link to this site appears in the page footer.