Doxygen meets SEQUENCE diagrams

I’ve been tinkering with Doxygen and SEQUENCE (see my previous post on this) to make them play well together for the documentation of the Daversy project. The goal was to have Doxygen automatically incorporate sequence diagrams into the resulting documentation, complete with a description of the diagram and links to other relevant parts of the docs.

I guess there are up sides to recovering from a knee surgery – it’s been years since I had the opportunity to spend a day on something like this.

We’ll start with a simple sequence diagram file that SEQUENCE can read and convert into an image.

user {
"client".extract {
  IDvsCore.CreateState->state { }
  CState:state."set db info"(provider, db server, username, password) { }
  CState:state.Extract {
    CDatabaseProviderFactory:dbprov_factory.GetDatabaseProvider->provider { }
    provider.Extract {
      database."read db structure"{ }
      provider."store db structure" { }
    }
  }
  CState:state.Save { }
}
}

This is an actual sequence diagram from the Daversy documentation that describes how the Extract command works, and when I run it through SEQUENCE, the following image is generated :


Is that cool or what?

Of course a sequence diagram without some accompanying text is not worth the effort, so we need a way to write a description along with the definition of the diagram. If you tried SEQUENCE out you might have noticed that the language it works with accepts C++ // style comments, and anyone who has used Doxygen knows it is quite happy with that (we can use the /// syntax it understands). Unfortunatelly SEQUENCE doesn’t work with C /* */ style comments, which I like better.

Now we know that we can create a file that contains both the sequence diagram itself and the comments we want to display along with it. All that remains is a bit of Doxygen trickery that will create a separate page for the sequence diagram and a small batch file that will generate the sequence diagram images before running doxygen.

In order to create a separate page for our sequence diagram, we’ll use the Doxygen \page command. We’ll refer to the actual image with the \image command and throw in some \section commands for a nice layout.

/// \page sequence_cmdline_extract Extract Sequence
/// \section Sequence Diagram
/// \image html cmdline-extract.png
///
/// \section Summary
///
/// This sequence diagram describes what happens when a user chooses to extract the
/// state of a datbase.
///
/// \section Description
///
/// The user is working with a client program, either the command line dvs.exe,
/// or the GUI Daversy. The client accesses the dvscore functionality through the
/// IDvsCore interface and requests a creation of a new CState object. It then
/// sets the provider that CState will use and calls the CState::Extract() method.
/// CState uses the CDatabaseProviderFactory to load the appropriate provider and
/// then calls the Extract  method of the provider.
user {
"client".extract {
  IDvsCore.CreateState->state { }
  CState:state."set db info"(provider, db server, username, password) { }
  CState:state.Extract {
    CDatabaseProviderFactory:dbprov_factory.GetDatabaseProvider->provider { }
    provider.Extract {
      database."read db structure"{ }
      provider."store db structure" { }
    }
  }
  CState:state.Save { }
}
}

I’ve saved that text under the name “cmdline-extract.sequence” and edited the Doxyfile configuration file to include all the files that have a .sequence extension during parsing (FILE_PATTERNS).

I’ve also created a file called “sequence-diagrams.dox” that looks like this :

/**
\page sequence_diagrams All Sequence Diagrams
\subpage sequence_cmdline_extract
\subpage sequence_another_one
\subpage sequence_yet_another_one
*/

It will act as a list of all the sequence diagrams we have in the project.

The batch file that glues this whole thing together is simplicity itself (assuming Doxyfile is in the same directory as the batch file and the sequence diagram files are in ./sequence):

@echo off
doxygen
for %%f in (sequence\*.sequence) do java -jar ..\tools\sequence\sequence.jar --headless %%f
copy sequence\*.png generated\html > nul

Naturally, all the references to the class and method names in the description of the sequence diagram are converted by Doxygen into links. The icing on the cake is that you can use the “\sa \ref sequence_cmdline_extract” Doxygen command anywhere in your source code comments to refer to the sequence diagram you made.

It is sad, but I don’t think I can upload the resulting HTML to blogger.com directly. So here’s a picture of what became of my efforts :


You can also take a look at the files I’ve made during this post in the Daversy source repository.

Comments are closed.