I appreciate documenting my code mostly because I forget how I wrote it – and sometimes worse – why I wrote it. An added benefit is if the documentation is well thought out, it greatly helps me figure out which way I should go within the variety of options to create code for the task at hand. I don’t mean the kind of comment that I run across all too often:
//open the gate
A comment that repeats the name of the function. What a waste of time and space! Certainly, the name of the function is super important to documentation. However the name should work with more context to understand why a program was written the way it is and why that function is needed.
Thanks to Those That Went Before
Thanks to Ron Sousa (@OpticalWorm) for showing us how to use Doxygen and Graphviz. I clearly saw the value after Ron walked us through one of his projects that had been “Doxygenated.”
The goal of this post is to add documentation to an Eclipse project (running on Mac OS X 10.10) – LED_TEST. LED_TEST is a very simple project I will be using to test the LED I have laid out on the LadybugBlueLite PCB.
I provided example Eclipse projects that use the NRF51 SDK in this GitHub repository. I peppered the source with Doxygen commands. Each contain a Documentation folder where you can view Doxygen’s output (open up the index.html file). The examples are located here in this GitHub repository.
The steps include:
Doxygen can be installed from this link. I downloaded Doxygen-1.8.10.dmg (56.0MB). I copied Doxygen.app into the Applications folder.
As pointed out in this post: Graphviz is open source software to create graphs using the dot language. Dot code can be used with Doxygen. I downloaded Graphviz from here. From what I can tell, the only thing used is the dot command line tool. Dot seems to work with either of the versions. I’m not completely sure because I was fiddling around trying to get graphical views to work within Doxygen. I’m pretty sure (but not positive) my challenge was not in the version of graphviz.
Important Notice !
Since December the 1st of 2009, the development and the maintenance of eclox are discontinued ! See Getting Involved to get information about development resources.
Despite the notice, I am throwing caution to the wind and going ahead with Eclox. Risky, I know, but…I optimistically believe the gain will be worth the risk.
Plug-ins are installed by going to Help->Install New Software…
Choose Add from the Install dialog box:
Add the Eclox repository:
Configure Eclox to use Doxygen
Time to tell Eclox where the Doxygen executable is located. This step is a little tricky. Go to Eclipse’s Preferences page
click the Add.. button.
Tricky part: Assuming you did like I did and copied Doxygen.app into the /Applications folder, the location of the Doxygen binary is located within Doxygen.app within the /Applications/Doxygen.app/Content/Resources . If you are not familiar with OS X application bundles, this wikipedia article may be helpful.
You know you have been successful if you see the version number.
Create a Doxyfile
Each Project needs a Doxyfile. As noted in the Doxygen documentation: [The doxyfile] configuration file is a free-form ASCII text file with a structure that is similar to that of a Makefile, with the default name Doxyfile. It is parsed by doxygen. Eclox adds a wizard to create one. Go to File -> New -> Other -> doxyfile .
A doxyfile has been created within the LED_TEST project:
Modify the Doxyfile
The easiest way to modify the Doxyfile is through the Doxyfile UI. Double clicking on the LED_TEST.doxyfile brings up the Doxyfile editor
Using the Doxyfile Editor
I used the settings above. However, I needed to set a few more properties before I could get the Diagrams to be generated. The additional properties can be set by going to the properties in the Advanced Tab. The Advanced Tab is located at the bottom of the editor.
Hurdle: Don’t forget DOT_PATH . Without it defined, Doxygen can’t find the dot utility provided by the GraphViz install.
Tip: When in the Advanced tab searching for a variable, go into the Custom Settings Tab and enter a search term like “DOT” to narrow down the properties to the ones you want.
I modified the following:
DOT_PATH = /usr/local/bin
EXTRACT_ALL = YES
EXTRACT_STATIC = YES
CALLER_GRAPH = YES
SOURCE_BROWSER = YES
You may want to modify some or none of the above. Perhaps splash around and find out what works for your project.
Add Doxygen Statements to your Source
Here is my simple main.c source with Doxygen statements:
* \file main.c
* \brief Test if the led on the Ladybug Blue Lite is working
* Author: Margaret Johnson
* \brief the Ladybug Blue Lite schematic identifies gpio pin 24 as the LED pin
#define LED_pin 24
* \brief Toggle the Ladybug Blue Lite’s LED
TRICKY: I could not consistently generate call graphs UNLESS I included the \callgraph Doxygen command in the function’s description.
USEFUL: Eclipse makes it easy to enter Doxygen commands. Start a line with /** then hit enter.
Eclox adds a toolbar button (image from this awesome post):
press the button to generate documentation for the opened project (or choose the project). A whole bunch of documentation files will be placed within the folder defined as the Output Directory in the Doxygen Editor step above. I set my Output Directory for this project to Documentation.
Double click on the index.html file to open the documentation within Eclipse.
Documentation Created With Doxygen
Here is an image of the documentation that was created by Doxygen as well as the graph by the Dot utility (from Graphviz):
From here I can jump to the source documentation (note “line 17” and “main.c” are in blue). Also, there is a call graph that makes it much easier to follow what is going on.
While I am new to Doxygen and Graphviz (the Dot utility), so far I am finding many positive reasons to consistently use as part of my programming process. The call graphs have been a great way to sift through the NRF51 SDK and gain a better understanding of what the libraries are up to as well as what code I should look at more closely.
Thanks for reading this far. Please find many things to smile about.