# 5 Best Eclipse Plugins: #1 (Eclox with Doxygen, Graphviz and Mscgen)

The #1 award in my list goes to Eclox+Doxygen+Graphviz+Mscgen. Yes, it is a single Eclipse plugin (Eclox) for Doxygen, and with two other powerful tools.  It solves a typical engineering problem: “How to document my project? And how to keep it up-to-date?”.

Like many other engineers, I do not like to write documentation. Because it is painful. I want to write code and program. Writing documentation for it should be fun too. And it should solve the problem that the documentation does not match what has been implemented. I’m a big fan of the ‘single source’ concept: information has to be in a single place, and not copied and distributed among different places. And here my #1 helps me doing this.

In a traditional way the following flow is used:

1. Create a design, specify and document the API
2. Implement the software
3. Write the user documentation
4. Ship it
5. Maintain and ship; and again, and again, and …

The problem starts with the fact, that rarely the implementation matches the initial design. It even gets worse after a few maintenance cycles: it is very hard to keep the documentation in sync with the actual implementation and project sources. And the user documentation will be easily out of sync too :-(.

It is already hard to write good documented code, and writing good source comments is an art on its own. Why not using the my precious source documentation in the sources and use it for the ‘written’ documentation? This is where I use Doxygen, GraphViz, Mscgen and the Eclipse Eclox plugin, all of them open source.

Doxygen is a compiler which generates documentation out of source files. Graphviz is a package to draw diagrams and graphs. Mscgen is similar to Graphviz, but simpler and optimized for message sequence diagrams. And Eclox is an Eclipse plugin which integrates everything into Eclipse.

## Installation

1. Doxygen: http://www.stack.nl/~dimitri/doxygen/ or www.doxygen.org
2. Graphviz: http://www.graphviz.org
3. Mscgen: http://www.mcternan.me.uk/mscgen/

Doxygen is required, Graphviz highly recommended, and Mscgen is optional.

After installing all of them, finally the Eclox Eclipse plugin: point Eclipse to the Eclox update site:

http://download.gna.org/eclox/update/

## Doxygen

With Doxygen my project sources *are* the documentation. Doxygen is using the comments in the code to generate the documentation. It is a compiler which compiles source (or text) files and extracts the embedded information. It supports many programming languages (C, C++, Java, …), and different output formats: HTML and PDF are very popular ones.

Doxygen is able to generate documentation from standard sources. But there are multiple ways of using special commenting styles to extend the information created. The Doxygen documentation lists different commenting styles.

With this, the following source is compiled by Doxygen:

/*! Masks for LEDs, this is an enum, and the values are power of two to make it
possible to build masks. The bit number also indicates the port bit number.
Make sure compiler treats enum's efficient (e.g. as unsigned char, as enum
by ANSI standard is int). */
typedef enum {
LED_0 = (1<<0), /*< Bit0 of port for LED0 */
LED_1 = (1<<1), /*< Bit1 of port for LED1 */
LED_2 = (1<<2), /*< Bit2 of port for LED2 */
LED_3 = (1<<3)  /*< Bit3 of port for LED3 */
} LED_Set;


It produces the following HTML output documentation:

enum LED_Set HTML Documentation

Another example is to document functions with their parameters:

/**
* \brief Switches on a set of LED.
* \param[in] Leds The set of LED to be switched on.
*/
void LED_On(LED_Set Leds);

void LED_On(LED_Set Leds) {
/*! \todo implement function */
}


The corresponding HTML documentation will look like this:

LED_On() Documentation

Note the \todo with will automatically added to a ‘To Do’ list in the documentation:

Todo List

## Graphviz

Graphviz is open source software to create graphs using the dot language. Dot code can be used with Doxygen. With the dot language I define nodes and edges, and the tool will place them automatically. For example I can define a graph with following dot code (example from the dot guide):

/**
\dot
digraph G {
main -> parse -> execute;
main -> init;
main -> cleanup;
execute -> make_string;
execute -> printf
init -> make_string;
main -> printf;
execute -> compare;
}
\enddot
*/


This then will create the following graph (source: dot guide):

small dot graph

The dot language makes it easy to create machine generated graphs too. That way dot is used in many other tools as visualization tool. And Doxygen is using of dot to create dependency graphs:

Dependency Graph

A nice feature is as well that the nodes have hyperlinks: click on a node an it jumps to the source file :-).

I’m using dot in my sources to enrich the documentation with graphs (a pictures may say more than 1000 words). Below is an example Doxygen/dot code:

/*! \brief Key scan routine which implements the state machine.
\dot
digraph example_api_graph {
node [shape=box];
DBNC_KEY_IDLE    [fillcolor=lightblue,style=filled,label="DBNC_KEY_IDLE" ];
DBNC_KEY_PRESSED [fillcolor=lightblue,style=filled,label="DBNC_KEY_PRESSED" ];
DBNC_KEY_RELEASE [fillcolor=lightblue,style=filled,label="DBNC_KEY_WAIT_RELEASE"];
DBNC_KEY_IDLE -> DBNC_KEY_PRESSED -> DBNC_KEY_RELEASE ;
DBNC_KEY_PRESSED -> DBNC_KEY_PRESSED ;
DBNC_KEY_IDLE -> DBNC_KEY_IDLE ;
}
\enddot
*/


This will generate the following output:

Debounce graph

## Mscgen

Mscgen is similar to Graphviz, but specialized for Message Sequence Charts (hence the Msc in its name). With Mscgen I can add following doxygen/msc code:

/**
\msc
a [label="Client"],b [label="Server"];
a-xb [label="get accel"];
a=>b [label="get accel"];
a<=b [label="ack"];
a<=b [label="accel data"];
\endmsc
*/


This will create following message sequence diagram into my documentation:

Mscgen Example Chart

Mscgen is ideal for any communication flow diagrams and greatly simplify and enhance my documentation.

## Eclox

All of above can be used without any IDE. But it is a lot of more fun within the Eclipse framework. And here is where Eclox comes into play: Eclox is a plugin which integrates Doxygen (and all above tools) into Eclipse and makes it really easy to use:

• Seamless build integration
• Editor coloring for Doxygen comments
• User interface for Doxygen configuration files
• Editor integration with automatic commenting
• Warning/Error parser
• Wizard to create configuration files

Eclox and Eclipse

## Eclox Plugin

Eclox automatically detects an existing Doxygen installation and reports it in the Preferences:

Doxygen Version

In case this fails, then this link gives some guidance how to set the settings in a manual way.

## Syntax Coloring

Eclox adds a Doxygen workspace default editor to the system:

Doxygen Workspace default

With this Doxygen comments are in blue color:

Doxygen source coloring

What is really cool: Eclox automatically adds comments in Doxgen format. For example I have this in my source:

int CalcPos(int currPos, int steps);


Then I simply can start a Doxygen comment (e.g. with /**) and press ENTER:

/**
*
* @param currPos
* @param steps
* @return
*/

int CalcPos(int currPos, int steps);


It automatically creates the comment block for me with parameters and return type, so I only need to fill in the content :-).

## New Doxygen Configuration File Wizard

Doxygen needs a textual configuration file. Eclox adds a wizard to create one using the menu File > New > Other > Doxyfile:

Creating New DoxyFile

## Doxyfile

The Doxygen configuration file (Doxyfile) is a simple text file which has comments in it to explain the settings:

# Doxyfile 1.7.2

# This file describes the settings to be used by the documentation system
# doxygen (www.doxygen.org) for a project.
#
# All text after a hash (#) is considered a comment and will be ignored.
# The format is:
#       TAG = value [value, ...]
# For lists items can also be appended using:
#       TAG += value [value, ...]
# Values that contain spaces should be placed between quotes (" ").

#---------------------------------------------------------------------------
# Project related configuration options
#---------------------------------------------------------------------------

# This tag specifies the encoding used for all characters in the config file
# that follow. The default is UTF-8 which is also the encoding used for all
# text before the first occurrence of this tag. Doxygen uses libiconv (or the
# iconv built into libc) for the transcoding. See
# http://www.gnu.org/software/libiconv for the list of possible encodings.

DOXYFILE_ENCODING = UTF-8

# The PROJECT_NAME tag is a single word (or a sequence of words surrounded
# by quotes) that should identify the project.

PROJECT_NAME = INTRO

# The PROJECT_NUMBER tag can be used to enter a project or revision number.
# This could be handy for archiving the generated documentation or
# if some version control system is used.

...


## Doxyfile Editor

Doxygen needs a text configuration file (the Doxyfile). With Eclox there is an editor view for that file:

Eclox doxyfile editor

The ‘Basic’ tab of that editor view gives access to the most important settings: The Input directories (I list here all the source directories I want to process), the Output Formats (I use mostly HTML. For PDF I usually select RTF or LaTeX), Diagrams and Mode selection.

There is a bug in the Eclox plugin: it looses the language settings for the ‘Optimize results for:’ settings. But that’s not a big deal.

## Compiling the documentation

Eclox toolbar button

The button automatically selects the Doxyfile of the current project. Otherwise it is possible to select a different Doxyfile.

Generating the documentation is like normally compiling source files: the Doxygen compiler reports what is going on to the Console View, and warnings/errors are reported in the Problems View.

## Other Documentation

It is possible to document things outside the source files. There are many different commands, \mainpage the most important one: it defines the main entry point of the documentation. Using \page and \section is is possible to organize the documentation, and \ref is used to reference labels:

Mainpage File with links to other files/pages

If using HTML, then the main entry point for the documentation is the index.html. Eclipse comes with a built in web browser which can be used to open that file. Or use any other HTML viewer:

index.html as documentation entry point

## Summary

The combination of Eclipse+Eclox+Doxygen+Graphviz simplifies my life: it makes documentation easy to generate. And it allows me to use a ‘single source’ approach: the sources are the documentation :-).

Happy Ecloxing :-)

—————————————————————————————–

Ranking:

## 16 thoughts on “5 Best Eclipse Plugins: #1 (Eclox with Doxygen, Graphviz and Mscgen)”

1. Thanks for explaining this. My work many times is taking a project that people are having problems with and solving those problems. This is a quick and easy way to get the high level overview of what is going on without reading every single C file.

2. Is there a way to integrate the generated HTML documentation into Eclipse when I press F1? I have to code a library containing doxygen documentation and I want other developers to access that documentation as easyly as possible.

3. You should add a note how to configure eclox to generate pdf documents

• Hi Biet,
I just had to add Eclox to my new Eclipse Kepler installation, and that worked fine for me (http://download.gna.org/eclox/update/). Can you verify that you have internet access? Maybe the server was down for a short period. Can you retry it?

4. Excellent post. I was checking constantly this weblog and I’m impressed!

Extremely useful information specially the final phase :) I handle such info
a lot. I was seeking this certain inf for a very long time.
Thank you and good luck.

5. Holy shit :)

I never came around to learn more about doxygen, but it always was on my todo list. Your explanation here has helped me a great deal and I am really glad I found it.

I am installing all the necessary tools and the plugin right now and will use them to better document my master thesis. The professors will thank you for leading me to Eclox :)

• Yes, and I always pass a ‘thank you’ to my students if they document with doxygen. Actually using doxygen is mandatory in my embedded systems programming course I teach :-)