Doxygen tips-n-tricks

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!

How to reassign a USB mount point

The minute you plug in a USB device in your computer, Window operating system assigns a drive letter (K:, J:, etc.) to the drive. Sometimes, the assigned drive letter conflicts with another network drive such as share drive. As a result, your USB is not visible or accesible by the Windows explorer.

To fix this problem, run diskmgmt.msc utility, find the drive in question and change its drive letter to something else that would not conflict with visible drives.

• Plug-in your USB device.
  
• On Windows desktop, click on Start -> run
• Type in diskmgmt.msc and click OK to bring up the Disk Manager:

• Find the USB removable media in the list you wish to change the drive letter for.
• Right-click on the drive entry, select Change drive letter/path, and change the drive letter.
• Unplug your USB device.
• Reboot the machine, plug the USB device back in and verify that it appears in the Windows Explorer and that device is accessible.