Doxygen documentation parser written by
Dimitri van Heesch (big thanks!) has been a part of my professional tool chest for a good part of the last ten years. Along with
Graphvis (layered drawings of directed graphs), a graph visualization toolkit from AT&T and Lucent Bell Labs, it provides a quick and intuitive way of documenting your source code. Doxygen output also helped me tremendously to navigate through a maze and learn quickly the inner workings of every new project I came across in the past.
First, you need to create a configuration file,
Doxyfile, either by running
doxywizard GUI or from command-line with '
doxygen -g' command.
Adjust Configuration File
First thing you would want to adjust is project name/number, document encoding and output directory.
PROJECT_NAME = Granule
PROJECT_NUMBER = 1.4.0
OUTPUT_DIRECTORY = dox
DOXYFILE_ENCODING = UTF-8
TAB_SIZE = 4
FULL_PATH_NAMES = NO
HIDE_UNDOC_CLASSES = NO
HIDE_IN_BODY_DOCS = YES
EXTRACT_ALL = YES
RECURSIVE = YES
If it is a "C" project, optimize for "C":
OPTIMIZE_OUTPUT_FOR_C = YES
For C++ project,
BUILTIN_STL_SUPPORT = YES
TEMPLATE_RELATIONS = YES
CLASS_GRAPH = YES
UML_LOOK = YES
GRAPHICAL_HIERARCHY = YES
You need to tell doxygen the file types to parse:
FILE_PATTERNS = *.h *.cpp
One thing I like about doxygen is its ability to shed some light on the function call chain in a program. For every function, it can optionally list all callers as well as call chain.
CALL_GRAPH = YES
CALLER_GRAPH = YES
REFERENCED_BY_RELATION = YES
COLLABORATION_GRAPH = YES
SOURCE_BROWSER = YES
INLINE_SOURCES = YES
ALPHABETICAL_INDEX = YES
GENERATE_TREEVIEW = YES (side pane)
SEARCHENGINE = YES
GENERATE_HTML = YES
HTML_OUTPUT = html
HTML_FILE_EXTENSION = .html
HTML_HEADER =
HTML_FOOTER =
HTML_STYLESHEET =
HTML_ALIGN_MEMBERS = YES
DISABLE_INDEX = NO
HAS_DOT = YES
DOT_IMAGE_FORMAT = png
DOT_FONTNAME = FreeSans
Cross-Referencing with Tag Files
If your project is an collection of disjointed libraries each within the boundary of its own package, you might want to enable cross-referencing with tagging feature of doxygen.
To better illustrate the concept, I will use my own software as an example. My flashcards program,
Granule, internally relies on
libassa (a collection of reusable shared code). In my Linux development environment, I have the following code arrangement:
Library
/path/to/libs/libassa/assa/
|
|-/dox/
| \--html/
| \--index.html
|--{*}.h
|--{*}.cpp
|--Makefile
\--Doxygen-lib
Application
/path/to/apps/granule/src
|
|--/dox/
| \--html/
| \--index.html
|--{*}.h
|--{*}.cpp
|--Makefile
\--Doxygen-app
The two paths are distinctly different. In order for the HTML documentation generated by Doxygen-app include references to the documentation generated by Doxygen-lib, we need
- configure Doxygen-lib to generate its tag file
- configure Doxygen-app to include external tag file(s) to resolve external references
With this in mind, let's look at the syntax of both configuration files:
--- Doxygen-lib ---
GENERATE_TAGFILE = dox/html/libassa.tag
--- Doxygen-app --
TAGFILES = /path/to/libs/libassa/assa/dox/html/libassa.tag=/path/to/libs/libassa/assa/dox/html
BTW, the path can be either absolute (as show in the example above) or relative. As you can see for yourself, the syntax of the TAGFILES parameter is a bit awkward by any standards. I would prefer instead an option of an environment variable to resolve the location of tag files which is more suited for a team of collaborative developers.
However, it gets the job done and that is what's important at the end of the day.
Happy coding!
