UML like Activity Diagrams with Moritz and Doxygen

This tutorial part describes how to create UML like activity diagrams with Moritz and how to
include them in the documentation created by Doxygen.

Please refer also the tutorial part that explains how to set up the used tools and the architecture of
the example project as well as the provided sub-directories for Moritz and Doxygen.

Content
UML like Activity Diagrams with Moritz and Doxygen......................................................................1
Common Explanations.....................................................................................................................2
The Moritz Configuration...........................................................................................................2
The Doxygen Configuration.......................................................................................................2
Note ............................................................................................................................................2
Including single Diagrams...............................................................................................................3
Splitting huge diagrams ..................................................................................................................5
Big functions will result in big diagrams ...................................................................................5
Excluding function parts.............................................................................................................7
Including the Part-Diagrams to the Doxygen Output................................................................11
Including Diagram Collections for a complete Source-File..........................................................13
Replacing single diagrams by Description Tables ...................................................................13
Setup diagrams as related pages................................................................................................15
Set up of Link References.........................................................................................................18
Other Diagram Modifications........................................................................................................20
Point out Sub Blocks.................................................................................................................20
Show the Original Source.........................................................................................................21
Independent Comment..............................................................................................................22
Resources and Links......................................................................................................................23
Common Explanations
Please read the Chapter “Run and Explore” in the tutorial introduction to learn how Moritz and
Doxygen will be set up basically for these tutorials. This chapter explains only some points which
may be important in this special case.

The Moritz Configuration

Since this tutorial shows only how to include UML like activity diagrams into the doxygen html-
output there will be now configuration for other diagram-types.

The configuration files used are:

• ansi_c_abc2xml_cfg.xml :
• configuration of abc2xml to parse the sources
• ansi_c_xml2abc_cfg_uad.xml :
• configuration of xml2abc to create UML like activity diagrams

Thus the create-script contains only one call for xml2abc.

The Doxygen Configuration

Since Doxygen should use the dot scripts created by Moritz the location where to find them has to
be configured in the “Doxyfile”. This is done by adding the path-string to the configuration option
“DOTFILE_DIRS” like this:
DOTFILE_DIRS = ../moritz/dot

Note
• The term “UML like” means that the generated diagrams may differ in some details from the
standard defined for UML. Please refer the examples given in the documentation of Moritz
(chapter Comment-Models) to learn more.
• To update the content of the Doxygen an update Moritz has to be run first if the diagrams
should be updated.
• Since UML like activity diagrams will be generated as dot scripts and will be transferred
into graphics by the dot tool the Graphviz package is needed to use them
• Once the diagram images are created they can be used for all kinds of documentation that is
able to contain graphics.
Including single Diagrams
All UML like activity diagrams generated by Moritz are located in the sub folder moritz/dot. For
every function there is one file that name contains the file name and the function name. Note the
“_c_F_” in between is the file attachment “.c” and a splitting symbol “_F_” between file and
function name.
For using dot-scripts Doxygen provides the command “dotfile” that expects the file name as
parameter. It is possible to extend the file name with a folder path string. But the more convenient
way is to add the folder path to the list of dotfile-dirs (DOTFILE_DIRS) in the “Doxyfile”

In the source example this command is added in the h-files into the function comments.
/*!
@ingroup REGULATOR
@brief move to the given position
@param position point to reach

@dotfile regulator_c_F_moveTo.dt
*/
void moveTo(int position);

The content of the c-source will not be changed

void moveTo( int position)
{
switch(position)
{
case PositionBeginn:
{
parkAtBegin();
}break;
case PositionEnd:
{
parkAtEnd();
}break;
default:
{
if((position>=PositionMin)&&(position<=PositionMax))
{
placeAt(position);
}
else
{
printf("position %d is out of bounds\n", position);
}
}break;
}
}
The Doxygen output contains now as additional part the UML like activity diagram:

Please explore the example folder “UML_ActivtyDiagrams_1” to see the result.

Splitting huge diagrams

Big functions will result in big diagrams

This is one function from the example:

void placeAt(int position)
{
int CurrentPosition = 0;
static int OldPosition = 0;
int RemainingSteps = 20;
int Tolerance = 1;

CurrentPosition = getPosition(1);
printf("\nstart position: %d \n", CurrentPosition);

while( (RemainingSteps >0 )

&&(abs_int(CurrentPosition - position) > Tolerance)
) // do a limited number of times until position inside tolerance
{
OldPosition = CurrentPosition;
CurrentPosition = getPosition(1);
printf("current position: %d \n", CurrentPosition);
if((position - CurrentPosition)>0)
{
if( (CurrentPosition - OldPosition)
< ((position - CurrentPosition)/2)
)
{
moveForwards(1);
TRIGGER_SIMULATION("moving forwards \n");
}
else
{
stop(1);
TRIGGER_SIMULATION("stop \n");
}
}
else if((position - CurrentPosition)<0)
{
if( (OldPosition - CurrentPosition)
< ((CurrentPosition - position)/2)
)
{
moveBackwards(1);
TRIGGER_SIMULATION("moving backwards \n");
}
else
{
stop(1);
TRIGGER_SIMULATION("stop \n");
}
}
--RemainingSteps;
}
printf("end position: %d \n", CurrentPosition);
}
Without modification this will be the diagram:

Even this diagram seems to be easier to survey as an nassi shneiderman diagram its size becomes a
problem since it is not small enough to be displayed on one page without shrinking it
Unfortunately there is no automatic way to solve this problem since Moritz is not able understand
the idea behind the source. It makes no sense to define default parts to be excluded out of a diagram
since this may result in placing the cut inside a sequence.
Excluding function parts

As Doxygen Moritz offers special commands which have to be used as comments inside the active
code. In this example the skip and exclude commands are used together with the auxiliry
commands beginBlock and endBlock:
void placeAt(int position)
{
int CurrentPosition = 0;
static int OldPosition = 0;
int RemainingSteps = 20;
int Tolerance = 1;

CurrentPosition = getPosition(1);

//@MRTZ_skip debug-output
printf("\nstart position: %d \n", CurrentPosition);

while( (RemainingSteps >0 )

&&(abs_int(CurrentPosition - position) > Tolerance)
) // do a limited number of times until position inside tolerance
{
// @MRTZ_exclude next_regulation
// @MRTZ_beginBlock
OldPosition = CurrentPosition;
CurrentPosition = getPosition(1);
// @MRTZ_skip debug-output
printf("current position: %d \n", CurrentPosition);
if((position - CurrentPosition)>0)
{
// @MRTZ_exclude forwards
if( (CurrentPosition - OldPosition)
< ((position - CurrentPosition)/2)
)
{
moveForwards(1);
// @MRTZ_skip
TRIGGER_SIMULATION("moving forwards \n");
}
else
{
stop(1);
// @MRTZ_skip
TRIGGER_SIMULATION("stop \n");
}
}
else if((position - CurrentPosition)<0)
{
// @MRTZ_exclude backwards
if( (OldPosition - CurrentPosition)
< ((CurrentPosition - position)/2)
)
{
moveBackwards(1);
// @MRTZ_skip
TRIGGER_SIMULATION("moving backwards \n");
}
else
{
stop(1);
// @MRTZ_skip
TRIGGER_SIMULATION("stop \n");
}
}
// @MRTZ_endBlock
--RemainingSteps;
}
// @MRTZ_skip debug-output
printf("end position: %d \n", CurrentPosition);
}
Different to Doxygen commands Moritz commands are not used inside special comments but in
normal ones without special start-tags. Like Doxygen commands a Moritz command starts with a @
or with a \ but directly followed by ”MRTZ_” .
This is the resulting main diagram simpler and thus smaller than the not tailored one:

The use of the skip command over the printf-command together with the parameter “debug-output”
//@MRTZ_skip debug-output
printf("\nstart position: %d \n", CurrentPosition);
results in a line with a reduced content as defined as parameter.

The use of the exclude command together with beginBlock and endBlock around the source
command-sequence inside the while-loop
while( (RemainingSteps >0 )
&&(abs_int(CurrentPosition - position) > Tolerance)
) // do a limited number of times until position inside tolerance
{
// @MRTZ_exclude next_regulation
// @MRTZ_beginBlock
●
●
●
// @MRTZ_endBlock
--RemainingSteps;
}
results in cutting out the command-sequence and displaying it as extra diagram:

But this part of the function contains excluded parts also.

The use of the exclude command alone operates only with the following source-command
// @MRTZ_exclude forwards
if( (CurrentPosition - OldPosition)
< ((position - CurrentPosition)/2)
)
{
●
●
●
}
else
{
●
●
●
}

If this source-command contains sub-commands like a decision or loop does this sub-commands are
effected also:
If a similar exclude command is used before the second if-command a similar result occurs.

Furthermore the skip command is used again but without a parameter:

{
moveForwards(1);
// @MRTZ_skip
TRIGGER_SIMULATION("moving forwards \n");
}
The result is a totally suppress of the effected source-command.
Including the Part-Diagrams to the Doxygen Output
In the case of UML like activity diagrams excluding part-diagrams means to create separate dot-
scripts and thus for every part diagram an own dotfile command has to be added to see the diagram
in the Doxygen output. Furthermore somewhat like a headline may be nice.
Thus the associated part in the header file will look like this:
/*!
@ingroup REGULATOR
@brief move until the given position is reached
@param position point to reach

<H1> placeAt </H1>

@dotfile regulator_c_F_placeAt.dt

<H1> placeAt next regulation </H1>

@dotfile regulator_c_F_placeAt_next_regulation.dt

<H1> placeAt forwards </H1>

@dotfile regulator_c_F_placeAt_next_regulation_forwards.dt

<H1> placeAt backwards </H1>

@dotfile regulator_c_F_placeAt_next_regulation_backwards.dt .dt
*/
void placeAt(int position);

With every new exclude this special comment has to be extended and with every changing the name
of an excluded part the content of this bloc has to be changed also. With distribution Moritz 2.0.2 an
extended internal configuration will be shipped in the language-package for ANSI-C that is
automatizing this task. After running Moritz the sub folder “moritz/dot” contains not only dot-
scripts but text-files also. For every function there is one txt-file that name contains the file name
and the function name. Note the “_c_F_” in between is the file attachment “.c” and a splitting
symbol “_F_” between file and function name.

For the example-Function “placeAt” in the source module “regulator” there is a file called
“regulator_c_F_placeAt.txt” with the following content:
/*!
@file regulator_c_F_placeAt.txt

<H1> placeAt </H1>

@dotfile regulator_c_F_placeAt.dt

<H1> placeAt next regulation </H1>

@dotfile regulator_c_F_placeAt_next_regulation.dt

<H1> placeAt forwards </H1>

@dotfile regulator_c_F_placeAt_next_regulation_forwards.dt

<H1> placeAt backwards </H1>

@dotfile regulator_c_F_placeAt_next_regulation_backwards.dt
*/
This file contains a Doxygen special comment-block and since its file-attachment is “.txt” this
attachment hast to be added to the list of file patterns “FILE_PATTERNS” in the configuration file
by adding “*.txt” to make text files known as files to evaluate. Now all additional text files can be
added like normal sources in the list of input files or input folders “INPUT”:
INPUT = ../src/component \
../src/simulation/controller.c \
../src/simulation/controller.h \
../src/stimulation/main.c \
../src/stimulation/main.h \
./texts/mainpage.txt \
../moritz/dot
Just by mentioning the folder-path it is possible to evaluate all files with an attachment mentioned
in the file pattern list. In the case that the folder contains some files which should not be used there
is a configuration tag in the “Doxyfile” called “EXCLUDE” that works like the “INPUT” tag and is
used to hold a list of files which should not be evaluated.

But this is only the half of the work. Even Doxygen is now parsing the text files files with the
attachment “.txt” will be not mentioned in the list of files inside the Doxygen output and actually
this is not wanted. The goal of evaluateing this files is to create inside the Doxygen database an
independent documentation-block than can be used somewhwer else with the Doxygen command
copydoc. This will be done by using the Doxygen command file in the first line of the special
comment:
/*!
@file regulator_c_F_placeAt.txt
●
●
●
*/
The file command together with the name of the containing file ensures that Doxygen creates an
independent documentation block just for this file. Even it is not used to document this file it can be
used as parameter for the Doxygen command copydoc:

/*!
@ingroup REGULATOR
@brief move until the given position is reached
@param position point to reach

@copydoc regulator_c_F_placeAt.txt
*/
void placeAt(int position);

Now the content of the header comment is as simple as before and every new or changed exclude
will be considered automatically.

Please explore the example folder “UML_ActivtyDiagrams_2” to see the result.

Including Diagram Collections for a complete Source-File

Replacing single diagrams by Description Tables

If the diagrams are very huge or they are split in many sub diagrams they may overload the
document of the functions. Even the diagrams may look nice in the first moment, they are only
interesting those who are responsible for the development or maintenance of the source-code.
Those who just want to use the functions in their own code may get lost in the description of all this
details.
Thus it is better to add the diagrams as related pages and to replace the single diagrams in the
documentation function by some links to the diagrams. Therefore Moritz offers the creation of
description tables.
The first step is to define the description tables by using the Moritz command describe. Its first
parameter is the name of the function or the identifier of an excluded function part. Optional a free
text is following that describes how the function or its excluded part works internally.

/* @MRTZ_describe placeAt
repeat calling the regulation until destination or a time-out is reached
@MRTZ_describe next_regulation
decide in which direction to move
@MRTZ_describe forwards
force moving forwards or stop moving depending on the remaining misplacement
@MRTZ_describe backwards
force moving backwards or stop moving depending on the remaining misplacement
*/
void placeAt(int position)
{
● ● ●
while( (RemainingSteps >0 )
&&(abs_int(CurrentPosition - position) > Tolerance)
) // do a limited number of times until position inside tolerance
{
// @MRTZ_exclude next_regulation
// @MRTZ_beginBlock
● ● ●
if((position - CurrentPosition)>0)
{
// @MRTZ_exclude forwards
if( (CurrentPosition - OldPosition)
< ((position - CurrentPosition)/2)
)
{
● ● ●
}
}
else if((position - CurrentPosition)<0)
{
// @MRTZ_exclude backwards
if( (OldPosition - CurrentPosition)
< ((CurrentPosition - position)/2)
)
{
● ● ●
}
}
// @MRTZ_endBlock
--RemainingSteps;
}
● ● ●
}
This will be normally done in the c or cpp file of the module and not in the header. On the one side
putting all Moritz commands into function defining files reduces the amount of files Moritz has to
analyze on the other side should the description table contain information how the function works
and not what it delivers, what means it describes the algorithm and not the data-interface.
Furthermore it is easier to ensure that the description table will be updated if the algorithm will be
changed or the excludes.
Once the description tables are defined in the source-code a new run of Moritz will result in a new
subfolder “moritz/des”. Here for every function with a defined description table one text file is
available, that defines a table like this:

Details of Algorithm :
placeAt repeat calling the regulation until destination or a time-out is reached
next_regulation decide in which direction to move
forwards force moving forwards or stop moving depending on the remaining misplacement
backwards force moving backwards or stop moving depending on the remaining
misplacement

Depending on some detailed configuration inside the distribution of Moritz the files have nearly or
exactly the same names as the files for the single diagrams. Thus the necessary changes in the
source-headers are very small as long as the Doxygen command copydoc is already in use as
described in the chapter above. But the list of “INPUT” sources in the “Doxyfile” has to be
extended.
INPUT = ../src/component \
../src/simulation/controller.c \
../src/simulation/controller.h \
../src/stimulation/main.c \
../src/stimulation/main.h \
./texts/mainpage.txt \
../moritz/des

Now the single diagrams will not be included anymore but the description tables. The description
tables contain links currently leading to nowhere. To change this diagram collections have to be
added as related pages.
Setup diagrams as related pages

In addition to the UML like activity diagrams generated by Moritz for single functions the sub
folder moritz/nsd contains for every analyzed source file a collection of all diagrams associated with
all functions inside the single source. The name of this txt file is the same as the original source but
its file-attachment is added with an underscore ( _ ).

Different to the diagrams of single functions they add them as related pages by using the Doxygen
commands “page” and “subpage” in addition.

/*!
@page DIAGRAMS Activity Diagrams
@subpage diagrams_regulator_c
*/

/*!
@page diagrams_regulator_c regulator.c

@section uad_setMax
@dotfile regulator_c_F_setMax.dt

@section uad_setMin
@dotfile regulator_c_F_setMin.dt

●
●
●

@section uad_parkAtBegin
@dotfile regulator_c_F_parkAtBegin.dt

@subsection uad_parkAtBegin_next_regulation
@dotfile regulator_c_F_parkAtBegin_next_regulation.dt@section uad_placeAt

●
●
●

@section uad_abs_int
@dotfile regulator_c_F_abs_int.dt
*/

This is the content of the generated collection file for the example module “regulator”.
The first comment-block is used to create a root page:
/*!
@page DIAGRAMS Activity Diagrams
@subpage diagrams_regulator_c
*/

This root page gets as sub pages the page with the actual diagram collection .
For the collection an additional comment is used to create its associated page
/*!
@page diagrams_regulator_c regulator.c

@section uad_setMax
@dotfile regulator_c_F_setMax.dt

@section uad_setMin
@dotfile regulator_c_F_setMin.dt

●
●
●

@section uad_parkAtBegin
@dotfile regulator_c_F_parkAtBegin.dt

@subsection uad_parkAtBegin_next_regulation
@dotfile regulator_c_F_parkAtBegin_next_regulation.dt@section uad_placeAt

●
●
●

@section uad_abs_int
@dotfile regulator_c_F_abs_int.dt
*/

While for the root page the first parameter the internal identifier is more or less not important it is
very important how the identifier parameter is designed since it influences the name of the
generated part file of the Doxygen output located in the folder html. What is essential for setting up
link references.
Since this diagram-collections are text files which contain Doxygen special comments they have to
be added to the list of “INPUT” sources in the “Doxyfile” :
INPUT =../src/component \
../src/simulation/controller.c \
../src/simulation/controller.h \
../src/stimulation/main.c \
../src/stimulation/main.h \
./texts/mainpage.txt \
../moritz/des \
../moritz/dot/controller_c.txt \
../moritz/dot/gear_c.txt \
../moritz/dot/inswitch_c.txt \
../moritz/dot/main_c.txt \
../moritz/dot/measure_c.txt \
../moritz/dot/outswitch_c.txt \
../moritz/dot/regulator_c.txt \
../moritz/dot/voltage_c.txt
Set up of Link References
Once the single diagrams are replaced by description tables and the associated diagram collections
are added it may occur that the links in the description tables are still not working. The reason is
that the file names created by Doxygen for the related pages differ from those expected by Moritz
while creating the description tables.
This is the Doxygen special comment-block of a description table:

/*!
@file regulator_c_F_parkAtBegin.txt

<b> Details of Algorithm :</b>

<TABLE border="0" cellspacing="5" cellpadding="0">
<TR>
<TD align="left" valign="top">
<a href="diagrams_regulator_c.html#uad_parkAtBegin">
parkAtBegin
</a>
</TD>
<TD align="left" valign="top">
repeat calling the regulation until destination or a time-out is reached
</TD>
</TR>
<TR>
<TD align="left" valign="top">
<a href="diagrams_regulator_c.html#uad_parkAtBegin_next_regulation">
next_regulation
</a>
</TD>
<TD align="left" valign="top">
force moving backwards or stop moving depending on the remaining misplacement
</TD>
</TR>
</TABLE>
*/

Very important is to ensure that Doxygen is using in its html output “doxygen/html” for the related
pages containing the diagram-collections the same file names like expected in the a-tags of the
description tables mentioned in the attribute href before the hash ( # ).
The first step is to use as first parameter of the page command in the Doxygen comment-block that
defines the related page exactly this file name but without the attachment since this parameter is
used to define the name of the corresponding output file
/*!
@page diagrams_regulator_c Regulator
@htmlinclude regulator_c.html
*/

But once the original source-name contains capital case letters this is not enough since capital
letters may lead to strange file names in the Doxygen output since Doxygen tries to ensure that
operation systems like windows which are not case sensitive will not exchange files if two file
names differ only in the case of their letters.
To change this behavior the configuration tag “CASE_SENSE_NAMES” has to be set to “YES”
CASE_SENSE_NAMES = YES

Please explore the example folder “UML_ActivtyDiagrams_3” to see the result.

Other Diagram Modifications

Moritz offers some more possibilities to modify Diagrams. Please take look to the following
examples and refer to the chapter “MRTZ-Commands” and its examples to learn more about it

Point out Sub Blocks

Pointing out sub-blocks of a function defines at least a kind of framing together with an additional
identifier. But for a better highlighting a special background color may be given.
Show the Original Source

Big expressions may be deform the whole diagram and it would be displayed not easy to survey and
especially if the developer of the source spent a lot of effort in a clear line format this is very
disappointing.

So sometimes it is better to display the real source lines than a diagram.

Independent Comment

Normally Moritz expects that comments are describing single source lines and tries to show them
together. But it is also possible to have comments which will be displayed alone.
Resources and Links

For dowloading the mentioned tools and further information about them please reffer the following
links.
1. Moritz : distribution of the script generator
• http://sourceforge.net/projects/Moritz/
2. MuLanPa : project used to develop the grammar and parser for Moritz
• http://sourceforge.net/projects/mulanpa/
3. Doxygen : tool to document software source
• http://www.Doxygen.org/
4. Graphviz : collection of diverse graphic tools
• http://www.graphviz.org/
5. Mscgen: tool to generate message sequence charts
• http://www.mcternan.me.uk/mscgen
6. Code::Blocks : IDE for text based software projects
• http://CodeBlocks.org/