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

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

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

LED_On() Documentation

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

Todo List

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

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

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

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
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 Example Chart

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 and Eclipse

Eclox Plugin

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

Doxygen Version

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

Doxygen Workspace default

With this Doxygen comments are in blue color:

Doxygen source coloring

Doxygen source coloring

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:

Creating New 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

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.

The ‘Advanced’ Tab gives access to all settings:

Doxyfile Advanced Tab

Doxyfile Advanced Tab

Compiling the documentation

Eclox adds a toolbar button:

Eclox toolbar button

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

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 documenation entry point

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:

About these ads

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

  1. Pingback: 5 Best Eclipse Plugins: #2 (AnyEdit Tools) | MCU on Eclipse

  2. Pingback: 5 Best Eclipse Plugins: #3 (System and Desktop Search) | MCU on Eclipse

  3. Pingback: 5 Best Eclipse Plugins: #1 (Eclox with Doxygen, Graphviz and … | Laughing

  4. 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.

    Like

  5. Pingback: Editor Templates in Eclipse | MCU on Eclipse

  6. Pingback: Low-Level Coding with PDD (Physical Device Driver) | MCU on Eclipse

  7. Pingback: Compiling Documentation and Presentations: LaTeX | MCU on Eclipse

  8. 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.

    Like

  9. 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.

    Like

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

    Like

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

      Like

  11. Dear all,
    I have installed all plugins, but after runnig I have got this error :
    error: problems opening map file C:/Users/Nadia/workspace/C++/html/structunitex_1_1virtualfile_1_1_v_f_s___i_n_o_d_e____coll__graph.map for inclusion in the docs!
    If you installed Graphviz/dot after a previous failing run,
    try deleting the output directory and rerun doxygen.

    Please I need your help,
    Thinks

    Like

  12. This article is really about Eclox with the proper additional plugins necessary for it to work fully – or almost fully, so I was a bit disappointed.

    It would be great if it generated PDF documentation by clicking the @. It doesn’t. You first need to install LATEX (full seems to be required) and maybe 10GB to 20GB later you can generate it outside of Eclox. But isn’t that the sort of thing that an IDE is supposed to do for you? With a bit of polishing up and optimizing defaults for newbies it has potential to be a nice development tool like javadoc.

    Like

    • Doxygen is really primarily about generating HTML (which works great). PDF is either over .rtf of LaTeX. But LaTeX is really something for advanced users. So you might be better to take the .rtf and then convert the file into a pdf in a separate step.

      Like

  13. Pingback: Constructing a Classroom IDE with Eclipse for ARM | MCU on Eclipse

  14. Pingback: Automatic Documentation Generation: Doxygen with Processor Expert | MCU on Eclipse

  15. I’d like to use eclox for my Java code (Android Apps) but every time when i try to a doxyfile i get the error Doxygen Error
    An error occured while running doxyge.eclox.core.doxygen.RunException:

    Like

      • I also use Juno. At the moment I created the Doxyfile with Doxywizard and copied the Doxywizard into the project. In this way it works. But for a new project i need to create the doxyfile with doxywizard again.

        Like

      • Ok, I see. Yes, you need to create that .doxyfile somehow first. What I usually do is a copy it from a previous project, and then change it. That way I do not need to run the doxywizard again.

        Like

  16. Hi Erich,
    After installed Doxygen, Graphviz, Mscgen and Eclox update
    When I compile the documentation
    I have this warning message:
    Warning: the dot tool could not be found at C:\ProgramFiles\Graphviz2.38\bin
    The dot.exe is installed in C:\ProgramFiles\Graphviz2.38\bin

    What can I do ?

    Thanks
    Raul Cortes

    Like

What do you think?

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s