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.

ContentUML like Activity Diagrams with Moritz and Doxygen......................................................................1

Common Explanations.....................................................................................................................2The Moritz Configuration...........................................................................................................2The Doxygen Configuration.......................................................................................................2Note ............................................................................................................................................2

Including single Diagrams...............................................................................................................3Splitting huge diagrams ..................................................................................................................5

Big functions will result in big diagrams ...................................................................................5Excluding function parts.............................................................................................................7Including the Part-Diagrams to the Doxygen Output................................................................11

Including Diagram Collections for a complete Source-File..........................................................13Replacing single diagrams by Description Tables ...................................................................13Setup diagrams as related pages................................................................................................15Set up of Link References.........................................................................................................18

Other Diagram Modifications........................................................................................................20Point out Sub Blocks.................................................................................................................20Show the Original Source.........................................................................................................21Independent 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 thestandard 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 diagramsince 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 areeffected 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 nameof an excluded part the content of this bloc has to be changed also. With distribution Moritz 2.0.2 anextended 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 isused 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 beused 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 thisdetails.

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 withall 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 andespecially 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/