Documenting Code the Easy Way – Part 1

Introduction

One of the most important yet most neglected tasks in embedded software development is writing and maintaining documentation.As software engineers we usually start strong by documenting everything but when the pressure is on, the boss is breathing down our necks, the client is antsy to see a functional prototype and the world is falling to shambles, we bury our heads in the code and just crank it out as fast as possible.We trick ourselves into believing that we’ll update that software document as soon as this deadline is met and things slow down a bit.In reality, the code either goes undocumented or is sprinkled here and there with half thoughts and gibberish in a rushed attempt to provide illumination into what has become the chaotic.

Documentation is a tedious and unrewarding part of our jobs.None of us want to do it, yet if we don’t, maintaining and updating the code can be become a nightmare for fellow developers or even forgetful future versions of ourselves.Luckily for us, documentation challenged developers have gone before us and a number of unique tools for easing our burden exist.These tools scan our source code and allow us to auto-generate our documentation by turning the comments that we already include in our code into documentation.A few examples of software tools that perform this function are JavaDocs, NaturalDocs and my all time favorite and primary focus of this article, Doxygen.

“Doxygen is a documentation system for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D.”[1] Doxygen offers a number of advantages to the software developer who is looking to keep their documentation consistent and up to date with what the source code is actually doing.Besides its free price being hard to beat (I haven’t yet found someone willing to pay me to use their software), Doxygen allows us to use the comments within header, source and other text files to generate our documentation in common formats such as HTML, RTF or PDF.Doxygen will allows the developer to show how a project was implemented by browsing files, classes, modules, variables and other types that are used in the program in addition to generating graphs to show how they interact with each other.

You can include just about any kind of data including images and equations.All the source code is available and hosted on SourceForge which allows us (if we are having a hard time sleeping or are just absolutely curious) to dig through the guts of the software and modify and tweak it for our own use.More importantly, Doxygen is widely used and supported through various software disciplines and for more than 10 years has been providing feature improvements and updates at least three times year.It can be customized to meet the needs of nearly any programmer through its support for multiple platforms and support of a plethora of programming languages.

In an effort to ease the time spent on developing documentation, this article will walk the developer through the Doxygen process of installation, configuration and the basics of code documentation.The end result will be a series of usable templates and configuration file which can be used by the developer to jump start the documentation for nearly any code project.

Installation

The home of Doxygen can be found at www.doxygen.org and the installation files can be downloaded from the download link on the right side of the page.While many of you may cringe, I installed my version of Doxygen on the Windows platform.In doing so, there were a number of additional packages which require installation as well if we are to generate Pdf’s and nicer looking graphs.First however, download and install Doxygen for your operating system of choice.

Next, download and install Graphviz from http://www.graphviz.org/. Graphviz is an open source graph visualization resource provided by AT&T research. Later, we will use this package by enabling the HAVE_DOT function in our configuration file to allow Graphviz to generate our graphs. This results in a more visually appealing result.

Finally, in order to convert our documentation into a Pdf, you will want to install LaTex (for a windows user I highly recommend the use of MikTex) and Ghost Script.Together these two packages will allow for pdf generation.

Setup a default directory structure for your documentation in your code project directory. An example would be C:ProjectDocsoutput, C:Project Docsimages, and C:Project Docsconfig. The Docs folder will be used to store our doxygen related files. A baseline directory structure can be found with this articles files which can be downloaded from www.beningo.com/resources/doxy-110123.zip. The output folder is where our generated documentation will be. Images is where we will store any images that we want included in our documentation (more on this later) and finally the config folder will be used to store our projects configuration file.

Basic Configuration File Setup

One of the advantages of using windows is that the old humdrum of command prompts and command options are a thing of the past (fine I admit I still use the command prompt for things like ipconfig but I can pretend right?).Doxygen for windows comes with a user interface called DoxyWizard which can be used to setup a Doxygen configuration file.DoxyWizard is located in the doxygen/bin directory.

DoxyWizard is broken up into a tabbed user interface where each tab acts as the stepping stone for setting up the project.First, we have a wizard tab that is extremely useful for configuring the initial project settings such as project name, logo, source location and where we want to store our documentation.Next, with the basics entered, the expert tab allows fine tuning of Doxygen for parameters such as file extensions, messages, html and many other options.Finally, we have the run tab where we can execute Doxygen based on the configuration file parameters and build our documentation.

Using the Doxygen wizard tab is fairly straight forward.Under project, enter the project name, a brief description and then the version or id.If your project has a logo, you can select the logo file and the logo will appear on the top of each html documentation page in the html header.The primary directory for source code and destination for the documentation can also be entered.An example of the setup page can be found in Figure 1.

Doxywizard

Figure 1: DoxyWizard Project Setup

In the mode menu, we can select our extraction mode and the programming language that we are using. For this example, we are going to extract documented entities only and optimize our output for C. Figure 2 shows an example of how the mode page should look when properly configured.

Figure 2: DoxyWizard Mode Setup

The output option allows us to select what type of file doxygen is going to generate. For this example, we are only going to generate html documentation but we also could have generated LaTex or an RTF file. If you want to change the color of the html pages it can be modified using the change color button. An example output configuration can be found in Figure 3.

Figure 3: DoxyWizard Output Setup

Finally the diagram page allows us to select which diagrams we are going to generate with our documentation. Since we’ve installed GraphViz we will select to use the dot tool. We can select which graphs we want to generate. It is useful to generate call and called by graphs in order to better understand how deep our function calls go. The configured diagram section can be found in Figure 4.

Figure 4: DoxyWizard Diagrams Setup

At this point Doxygen has enough configuration information for us to generate our first set of documentation.This can be done by simply moving to the run tab and pushing the “Run Doxygen” button.Doxygen will chew on the configuration file for a little while and begin processing the entire source repository.In addition it will generate any diagrams that we have requested it to generate.When “*** Doxygen has finished” is displayed in the status window, pushing the “Show HTML output” button will open the HTML document that we just generated.

Congratulations!You have just moved one step closer to spending less time documenting and more time coding.

Leave a Reply

Your email address will not be published. Required fields are marked *