BookmarkSubscribeRSS Feed

Introduction to Doxygen

Started ‎03-15-2021 by
Modified ‎11-09-2021 by
Views 4,508
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.comFigure 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 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.


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

 

Figure 5 - Graphviz output in Data ControllerFigure 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
Version history
Last update:
‎11-09-2021 03:57 PM
Updated by:

sas-innovate-2024.png

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