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

Here are the links to download the needed tools:

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://home.gna.org/eclox/#update-site

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:

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:

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

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):

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

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

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:

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:

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
arcgradient = 8;
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 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 Plugin

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

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:

With this Doxygen comments are in blue color:

Doxygen Auto Comments

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:

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:

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.

The ‘Advanced’ Tab gives access to all settings:

Compiling the documentation

Eclox adds a 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:

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:

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:

• Rank #1: Eclox
• Rank #2: AnyEdit Tools
• Rank #3: System and Desktop Search
• Rank #4: EHEP
• Rank #5: WickedShell