BookmarkSubscribeRSS Feed

Introduction to Doxygen

Started ‎03-15-2021 by
Modified ‎11-09-2021 by
Views 4,508
Paper 1077-2021

Tom Bellmer


Reusable code such as SAS macros needs to be exposed in such a way that makes it easy for others to see and understand your code. I often find myself having to open code to recall the parameters used in a macro that I wrote. What is needed is an organized collection of those macros to expose that information and more. That is where Doxygen comes into play. Doxygen is free software, released under terms of the GNU public license version 2. It is used to scan key annotated comments in source code to create standardized documentation. Dimitri van Heesch created Doxygen in 1997 as a cross-platform program written in C++. As a result you can run Doxygen under Linux, MacOS or Windows. This paper uses Windows 10 but most everything will port to other platforms unchanged. With Doxygen you can generate on-line documentation using HTML or in Latex, RTF, PDF and UNIX man pages. This paper will only cover HTML output. In all cases the documentation is extracted directly from the source code making it much easier to keep both synchronized. Doxygen got its name from the words document and generator where document was referenced as docs then dox while generator became gen. According to the Doxygen FAQ, the author was looking into lex and yacc, where a lot of things start with yy so the y slipped in to make it more pronounceable (as Docs-ee-gen with a long e).



To reinforce the concept of adding comments to a program header, I wrote a SAS® stored process to generate a standardized program header (see below). The idea was to be able to dissect the contents and create documentation from those comments. Below is a very simple SAS® macro function that uses the header, accepts three parameters and returns a hex string:


 Author: Tom Bellmer
 Created: 20180521 @ 15:18:13
 SAS Version: SAS 9.4 (TS1M3)
 Purpose: returns the SAS (CX) hex value from R, G, B values
 Usage: %let x = %rgb(255, 128, 0); /* returns CXFF8000 */
%macro rgbtohex(r, g, b);
/*EOF: */


It was my desire to create HTML based documentation with a list of macros in a treeview on the left similar to what is used on the website (see Figure 1). Unfortunately, that was not an easy endeavor requiring the use of JSON (JavaScript Object Notation) data and some advanced JavaScript code. After that I would still have to apply some custom CSS styles for aesthetics. When I discussed these issues with well-known SAS® guru, Allan Bowe, he recommended a product named doxygen that he had just started using.


Figure 1 - Treeview from 1 - Treeview from



The first step is to install doxygen by visiting the page for installation on your platform. At this time the latest release is version 1.9.1 (released January 8, 2021). From the downloads page, select sources and binaries and select the appropriate installer for your platform.

Doxygen uses a non-formatted ASCII configuration file (named Doxyfile by default) to store settings. To create the template configuration, run the following from the command line (if you omit the <config-file>, one named Doxyfile will be created): doxygen -g <configfile>


Figure 2 provides an overall flow of how doxygen works. The main areas of interest are the config parser and tag file parser.


Figure 2 - Doxygen flow diagramFigure 2 - Doxygen flow diagram


The case sensitive uppercase tag names are separated from the associated values by an equal sign (=). Reading in the 1.91 release of the generated doxyfile, there were 302 unique tags. You can edit those settings in a text editor or in doxywizard.

Doxywizard is a GUI front-end (see Figure 3) for configuring and running doxygen. You can specify a configuration file by specifying it from the File | Open… or Open Recent options. The important areas are the Wizard, Expert and Run tabs highlighted in red.


Figure 3 - Doxywizard GUIFigure 3 - Doxywizard GUI


The Wizard tab is used to quickly configure the most important settings while leaving the other options at their defaults. The Expert tab provides access to all the available options -
it is very detailed and covers all 300+ options. The Run tab is used to create the output based on the defined options that have been selected. Read the doxygen manual for complete details on all the options.


Next we will cover the steps needed in each of the source files to make them compatible with doxygen. This example uses the macro code from the first page and how it is refactored to work within the doxygen environment.

Use the JavaDoc style /** (slash followed by two asterisks) in the header section to signify this contains comments to be analyzed by doxygen. Special commands recognized by doxygen can start with a backslash (\) or an at sign (@).


I like to use the latter and start with a @file that resolves to the name of the file. This is followed by @brief or a one line brief description. Next up is @details to contain a longer, more detailed description of the code. Notice markdown language for the URL with a mouse over title as well as ‘>’ as a blockquote. In order to retain the “%” sign in your output, be sure it is indented not 2 but 4 spaces. That assumes a TAB_SIZE = 2 value in the Doxyfile configuration.

The @param command is used to describe parameters. @return or @returns starts a return value description. An @note command can be used to call out things that users should understand. The @version command can contain whatever you like but I use it to reveal the specific version of SAS® used when it was created. The @author displays just that and the @ToDo will write out a block quote to make the action stand out as well as create a separate page that is a collection of all @ToDo occurrences across all input files.


 @brief convert RGB to hex
 @details Usage:
 %put %rgbtohex(255, 128, 0);
 > CXFF8000
 Credit Perry Watts' inspiring [SUGI 28 paper](
 “Working with RGB and HLS Color Coding Systems in SAS Software”)
  r The decimal value (0 to 255) for the color red
  g The decimal value (0 to 255) for the color green
  b The decimal value (0 to 255) for the color blue
 @returns a hex value preceded by CX used by SAS graphics
 @note values < 0 or > 255 will generate erroneous values
 @version SAS 9.4 (TS1M3)
 @author Tom Bellmer
  Need to create more examples



From the doxywizard interface, click on the Run tab then Run doxygen. You can see the generated file by clicking on Show HTML Output or the index.html file located in the destination directory specified in the Wizard tab. See figure 4 for an example of the output. If you would like to see a more complete site that contains a collection of production ready SAS® macros using doxygen then visit the open source site


Figure 4 - Doxygen OutputFigure 4 - Doxygen Output


An even more impressive add on feature is the use of Graphviz and the DOT language to create data driven diagrams, but that is beyond the scope of this paper. However, as a teaser, here is an example of what can be done and is being done in the SAS® based Data Controller product that can be seen in figure 5 and in this video:


Figure 5 - Graphviz output in Data ControllerFigure 5 - Graphviz output in Data Controller



Doxygen is an extremely robust document generator that has been around for nearly 25 years and passed the test of time. There is no need to reinvent the wheel when you have free options like doxygen around.



Doxygen. “Generated Documentation From Source Code”. Accessed February 20, 2021.
Macro Core. “Production Ready Macros for SAS Application Developers”. Accessed February
20, 2021
Data Controller. “Flexible and Secure Data Modification”. Accessed February 20, 2021



Your comments and questions are valued and encouraged. Contact the author at:
Tom Bellmer

SAS and all other SAS Institute Inc. product or service names are registered trademarks or trademarks of SAS Institute Inc. in the USA and other countries. ® indicates USA registration. Other brand and product names are trademarks of their respective companies.


Appendix A - Common Doxygen Configuration Tag Names


TAG_NAME  Setting  Description
ALPHABETICAL_INDEX NO Alphabetical index of all compounds
ALWAYS_DETAIL_SEC NO Only create a detailed section if there is
something in that section
DISABLE_INDEX YES Control top index (tabs) at top of page
ENABLE_PREPROCESSING NO Evaluate all C-preprocessor directives
EXCLUDE   Specify files and/or directories that should be
excluded from the INPUT source files.
EXTENSION_MAPPING sas=Java Specifies the parser to use for a file extension
EXTRACT_ALL YES Ensure that all files in INPUT are processed
even those without any doxygen special
EXTRACT_LOCAL_CLASSES NO Include classes in documentation

Which file extensions to process in folders


Create a Latex file?


Create a tree-like index should be created


Hide friend compounds


Hide documentation inside body of function


Show members with full namespace scope


Hide undocumented classes


Hide undocumented members in files


Location of HTML files


User defined HTML header file


User defined HTML footer file


User defined CSS file


Specify one or more files or directories


Will undocumented member inherit


Insert tag for inline members


Directory that contains source files


Max # of lines - if 0 it is ignored


Text in title area


Title of most generated pages


Logo or icon max dimensions of max
dimension of 55px by 200 px


Search subdirectories


Prepend brief before detailed description


Create namespace page


List files generated at bottom of page


Create list of source files generated


Enable mouse over tooltips


Handling when parameters do not match


Hide comments from source


Show subgrouping


Tabbing space, min: 1, max: 16


Use a markdown file such as


Copy header for included code

Appendix B - Common Doxygen Special Commands


Command Description
@author {list of authors} Author’s name
@b <word> Displays text in bold
@brief {brief description} One line brief description
@date {date description} Display a date
@details {detailed
Detailed description
@e <word> Detailed description
@emoji “name” Displays an emoji using the specified name. Names can be
found here:
@file [<name>] Name of program
@image[‘{‘option’}’] <format> <file> Inserts an image into the documentation. Doxygen will look
for images in the IMAGE_TAG tag. Example:
@image html application.png
@li {item-description} Generates a simple list of items
@mainpage [(title)] Used to customize the index page. The tag
USE_MDFILE_AS_MAINPAGE is an alternative
@n Force a new line
@note {text} Indented notes
@param ‘[‘dir’]’ <parametername> {parameter
Starts a parameter description
@return {description of
return value}
Description of the return value
@see {references} One or more cross-references
@todo {what needs to be
Adds a TODO section and also creates a separate TODO list
@version {version number} Show a version
@warning {warning text} Displays a warning paragraph
Version history
Last update:
‎11-09-2021 03:57 PM
Updated by:


Available on demand!

Missed SAS Innovate Las Vegas? Watch all the action for free! View the keynotes, general sessions and 22 breakouts on demand.


Register now!

Click image to register for webinarClick image to register for webinar

Classroom Training Available!

Select SAS Training centers are offering in-person courses. View upcoming courses for:

View all other training opportunities.

Article Tags