Tags

,

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

void openTheGate(){

}

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.

In our embedded systems section of Contextual Electronics, Ron showed us how he uses Doxygen and Graphviz to document code.  I like having the documentation within the same location as the source.

Thanks to Those That Went Before

I found this post by Erich Styger to be exceptionally helpful in understanding what was going on.  Thank you Erich for your well written advice.

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

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.

Open Source

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

The steps include:

Install Doxygen 

Doxygen can be installed from this link.  I downloaded Doxygen-1.8.10.dmg (56.0MB).  I copied Doxygen.app into the Applications folder.

Install GraphViz

As pointed out in this postGraphviz 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.

Install Eclox

Eclox is an Eclipse plug-in that I found out about from this post.  When I looked at the Eclox home page, I was greeted with a concerning message:

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

 */

#include<stdint.h>

#include“delay.h”

#include“led.h”

/**

 * \brief the Ladybug Blue Lite schematic identifies gpio pin 24 as the LED pin

 */

#define LED_pin  24

/**

 * \callgraph

 * \brief Toggle the Ladybug Blue Lite’s LED

 */

int main(void){

  led_Init(LED_pin);

    for(;;)

    {

led_Toggle(LED_pin);

delay_ms(500);

    }

}

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.

Run Doxygen

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.

 

 

 

Advertisements