Introduction to Doxygen

[#1]

Paper 1077-2021

Author 

Tom Bellmer

Abstract

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).

INTRODUCTION

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:

/********************************************************************
 Program: rgbtohex.sas
 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);
 %sysfunc(compress(CX%sysfunc(putn(&r.,hex2.))%sysfunc(putn(&g.,hex2.))
 %sysfunc(putn(&b.,hex2.))))
%mend;
/*EOF: rgbtohex.sas */

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 support.sas.com 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 support.sas.com

INSTALLATION

The first step is to install doxygen by visiting the https://www.doxygen.nl/download.html 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>

CONFIGURATION SETTINGS

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 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 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.

SPECIAL COMMANDS

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.

/**
 @file
 @brief convert RGB to hex
 @details Usage:
 %put %rgbtohex(255, 128, 0);
 returns:
 > CXFF8000
 Credit Perry Watts' inspiring [SUGI 28 paper](https://bit.ly/3aiKJWo
 “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
*/

GENERATING OUTPUT

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 https://core.sasjs.io/.

Figure 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: https://vimeo.com/383391622

Figure 5 - Graphviz output in Data Controller

CONCLUSION

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.

REFERENCES

Doxygen. “Generated Documentation From Source Code”. Accessed February 20, 2021.
https://www.doxygen.nl/index.html
Macro Core. “Production Ready Macros for SAS Application Developers”. Accessed February
20, 2021 https://core.sasjs.io/
Data Controller. “Flexible and Secure Data Modification”. Accessed February 20, 2021
https://datacontroller.io/

CONTACT INFORMATION

Your comments and questions are valued and encouraged. Contact the author at:
Tom Bellmer
thomas.bellmer@gmail.com
https://KanSAScode.blogspot.com

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 characters
EXTRACT_LOCAL_CLASSES	NO	Include classes in documentation
FILE_PATTERNS	*.sas	Which file extensions to process in folders
GENERATE_LATEX	NO	Create a Latex file?
GENERATE_TREEVIEW	YES	Create a tree-like index should be created
HIDE_FRIEND_COMPOUNDS	YES	Hide friend compounds
HIDE_IN_BODY_DOCS	YES	Hide documentation inside body of function
HIDE_SCOPE_NAMES	YES	Show members with full namespace scope
HIDE_UNDOC_CLASSES	YES	Hide undocumented classes
HIDE_UNDOC_MEMBERS	YES	Hide undocumented members in files
HTML_OUTPUT	doxy	Location of HTML files
HTML_HEADER		User defined HTML header file
HTML_FOOTER		User defined HTML footer file
HTML_STYLESHEET		User defined CSS file
IMAGE_PATH		Specify one or more files or directories
INHERIT_DOCS	NO	Will undocumented member inherit
INLINE_INFO	NO	Insert tag for inline members
INPUT		Directory that contains source files
MAX_INITIALIZER_LINES	0	Max # of lines - if 0 it is ignored
PROJECT_BRIEF		Text in title area
PROJECT_NAME		Title of most generated pages
PROJECT_LOGO		Logo or icon max dimensions of max dimension of 55px by 200 px
RECURSIVE	YES	Search subdirectories
REPEAT_BRIEF	NO	Prepend brief before detailed description
SHOW_NAMESPACES	NO	Create namespace page
SHOW_USED_FILES	NO	List files generated at bottom of page
SOURCE_BROWSER	YES	Create list of source files generated
SOURCE_TOOLTIPS	NO	Enable mouse over tooltips
STRICT_PROTO_MATCHING	YES	Handling when parameters do not match
STRIP_CODE_COMMENTS	NO	Hide comments from source
SUBGROUPING	NO	Show subgrouping
TAB_SIZE	2	Tabbing space, min: 1, max: 16
USE_MDFILE_AS_MAINPAGE		Use a markdown file such as README.md
VERBATIM_HEADERS	NO	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 description}	Detailed description
@e <word>	Detailed description
@emoji “name”	Displays an emoji using the specified name. Names can be found here: https://gist.github.com/rxaviers/7360908
@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 description}	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 done}	Adds a TODO section and also creates a separate TODO list
@version {version number}	Show a version
@warning {warning text}	Displays a warning paragraph