tutorial for moritz · • message sequence charts ... opening the file “startdoc.html”. the...

Tutorial for Moritz

This tutorial part describes the basic starting point used from every other Moritz tutorial to explain the generation and use of:

• Nassi Shneiderman Diagrams

• UML like activity diagrams

• Message Sequence Charts

This part explains how to set up the used tools and the architecture of the example project as well asthe provided sub-directories for Moritz and Doxygen.

ContentTutorial for Moritz................................................................................................................................1

Moritz is a Script-Generator............................................................................................................2Set up the Moritz Distribution....................................................................................................4

The Tutorial Structure .....................................................................................................................5The Doxygen Folder...................................................................................................................5The Moritz Folder.......................................................................................................................5The Source Example...................................................................................................................6

The Scenario...........................................................................................................................6A Library with a Layer Structure...........................................................................................7

Run and Explore..............................................................................................................................8Set up of the Tutorial Main Part..................................................................................................8The Example Sources..................................................................................................................9The Moritz Configuration.........................................................................................................10

ansi_c_abc2xml_cfg.xml......................................................................................................10ansi_c_xml2abc_cfg_nsd.xml and ansi_c_xml2abc_cfg_uad.xml......................................12Create Script.........................................................................................................................13

Running Moritz ........................................................................................................................14The files generated by Moritz...................................................................................................15

XML.....................................................................................................................................15NSD......................................................................................................................................17DOT......................................................................................................................................18

The Doxygen Configuration.....................................................................................................19The Documentation generated by Doxygen..............................................................................20

Resources and Links......................................................................................................................21

Moritz is a Script-Generator

As help-tool for Doxygen Moritz is designed as a source-code analyzing program that generates algorithm describing diagrams of the functions and methods written in different programming languages. Originally this diagrams are generated as html files for example the nassi shneiderman diagrams. But today other output-formats are possible also for uml activity diagrams are generated as dot-scripts. Moritz 2 has now an own source parser and uses the xml output of Doxygen as additional information-base to get information about link destinations located in the documents generated by Doxygen. The output of Moritz may be included in a documentation generated by Doxygen via the commands "htmlinclude" or "dotfile".Moritz it self is split in 2 console- or terminal-applications which have to be started via command-line. With configuration-files you may control the general style of the diagrams. You can also change this configuration for a function or a part of a function by using special commands in the source-code.

Moritz is designed as one tool in a chain of tools. It could not be used as stand-alone application. Even Moritz 2 comes along with an own source-parser it doesn't create graphic files directly.

To parse the sources written in a programming language like C/C++, Phyton, Matlab or Pascal a parser tool called abc2xml is used to create a xml database that has an own project called MuLanPa . This tool creates for every source an xml file that contains a so called parser tree that describes the algorithm- structure. This xml file may be also used as input for other analytic tools. The Moritz binary xml2abc analyzes this system of xml files and creates several script-files to describe the diagrams. To get a graphical output a script-interpreting tool has to be used.

The native script-format of Moritz is html . So every common html browser may be used to view the diagrams as screen-output. But since today the dot-language is used to create dot-files for describing uml activity diagrams, the tool Dot has to be used to create real graphics like a jpg.

As a next step Moritz will be use to generate source-scripts for the tool mscgen also to generate message sequence charts.

To control the whole process of generating the xml scripts with Doxygen and generating the diagram-scripts with Moritz several files are used. To control the whole process of generating the xml scripts with abc2xml and xml2abc several files are used.

First of all the user starts a batch-file or terminal-script which calls abc2xml, xml2abc and perhaps additional tools to interpret the output of xml2abc sequentially.

• The parser abc2xml neads an own configuration file in xml-format. To learn more about abc2xml is recommended to read its manual at MuLanPa .

• The generator xml2abc neads an own configuration file in xml-format also. • It is possible to split the configurations of both tools in a user-file and some more detailed

configurations.

Set up the Moritz Distribution

Even Moritz can be used allone today it is still designed to be used togeterh with tools like Doxygen and dot from the Graphviz package. Furthermore in the future Moritz will be able to be used to create source-code for Mscgen .

The following set up of the Moritz distribution expects that at least Doxygen and the Graphviz package are installed.

The project page of Moritz provides in the file-section distributions for Windows and Linux as zip-files. To install the tools of itself, it is only neccessary to decompress the archives. But in addition the user has to open the command-scrip called "path_def" located in the sub-folder "cfg" of the distribution.

Here the following environment variables have to be corectly set:

• DOXY_PATH: location of Doxygen binary to use• DOT_PATH : location of dot-binary to use • HWS_BIN : location of hhc binary of Microsoft html help workshop (windows only)• PERL_PATH : location of Perl binary to use (for use with Matlab only)

Once this locations are defined the user can start the create script for his desired programming language. This provided script generates the complete documentation what can be started by opening the file “StartDoc.html”.

The Tutorial Structure

The Doxygen Folder

At least the Doxygen folder contains two sub-folder pictures and texts which are used to place some additional documenting content. Here you will find all graphics and additional text-files used for the documentation. Even the text files contain special c-comments their attachment is still “txt”.Thus this attachment has to be added to the list of “FILE_PATTERNS” inside the “DoxyFile”.

Parallel to the “DoxyFile” a command script is existing to call the “doxywizard”. Note to start Doxygen with its wizard it is necessary to install both regularly. If you just copy both binaries together in one folder on your computer without starting a real install process (depending on your operation system) you are able to start both binaries independent from each other but the doxywizard is not able to start Doxygen.

Once Doxygen was started result folders will be created which contain the files generated by Doxygen.

The Moritz Folder

At least the Moritz folder contains one sub folder cfg that contains the user configuration for the binaries “abc2xml” and “xml2abc”. To start the binaries the command script “create” will be used.

Once the Moritz binaries were started result folders will be created which contain the files generated by the Moritz binaries. The tool “abc2xml” is parsing the source-files and creates xml files which will be stored in the folder “xml”. The tool “xml2abc” is parsing the xml files and generates depending on the configuration other script-files which will be stored in the other folders like “nsd”,or “dot”.

A complete run of Moritz may be time consuming. Especially the parser abc2xml needs some time since different to a compiler the comments will not be deleted but evaluated by an extra process to be merged with the result of parsing the active code again in a final step. Depending on the size of the script files to generate the tool xml2abc may take some time also. To save time it is possible

The command script “_clearResult” may be used to delete the files (not the folders) generated by the Moritz binaries to ensure a clean run.

The Source Example

Moving Car Project

A small example c-source project should be used in diverse tutorials to explain the use of Moritz especially the use of the new Moritz 2 with its binaries abc2xml and xml2abc.

This document should give the user an idea of the example project itself. How Moritz provides helpwhile documentation and test will be explained in own documents. Never the less this example should be used to explain the use of Moritz and not how to solve the challenges described in the scenario.

Thus please take the scenario and the explained solution as it is even it may contain some questionable details. Once you learned how to use Moritz you may use the example to exercise since the documentation and test is always the base of improving the design.

The Scenario

Let's assume that we have the job to control the position of a toy-car that is able to move forwards and backwards between to mechanical barriers.

To observe the position we have one analogue sensor that transfers the current position to a voltage and two switches to get the binary information that a barrier is reached. The controller has the possibility to input the sensor-voltage as well as the switch-states. To move the car two binary outputs are used one or moving forwards and one for moving backwards.

A Library with a Layer Structure

To solve the challenge not only one source-module was used but 6.

• Interface-Layer : connection to the application

• regulator.c : provides control-functions

• Service-Layer : abstract execution of processes • measure.c : observe current position and reaching of a barrier • gear.c : moving forwards or backwards

• Terminal-Layer : controller periphery and hardware • voltage.c : evaluate the register of the controller analogue digital converter • inswitch.c : evaluate the states of the binary inputs• outswitch.c : write into the binary outputs to move into the desired direction

To round up the project and to compile it two additional files have to be added:

• Application-Layer : uses the library • main.c : contains just some calls of the interface-functions for testing purpose

• Hardware-Simulation : Provides the "Real World" • controller.c : provides the definition of the used register-variables

Run and Explore

The main task of this introduction is to learn how to setup the tools to run them and to explore the results. Since every main part of the Moritz tutorials comes along with an own root folder the setup procedure shown here has to be done in every main folder again. The reason for this is to ensure that later all main folders are usable independently from other tutorial parts.

Set up of the Tutorial Main Part

Every part of the tutorial comes along with its own example directory that contains 4 sub-folders:

• src : this folder contains an source-example used for the Tutorial

• Moritz : this folder contains a minimum of configuration to start the Moritz binaries

• Doxygen : this foldercontains the configuration of Doxygen

• codeblocks : this folder contains a project-file for the IDE Code::Blocks used to edit the source example.

Furthermore the root-directory contains a path_def script like the distribution:

• Moritz_PATH: location of Moritz distribution• DOXY_PATH: location of Doxygen binary to use• DOT_PATH : location of dot-binary to use • MSCGEN_PATH: location of MscGen binary (Message sequence chart generator)• HWS_BIN : location of hhc binary of Microsoft html help workshop (windows only)• PERL_PATH : location of Perl binary to use (for use with Matlab only)

The tutorial is using the Moritz distribution but not its user configuration. This means that environment-variables set in the “path_def “ script inside the tutorial directory has to be updated by the user as well as the one in the distribution. Different to the distribution the tutorial tries to split the call of Moritz and Doxygen as far as possible to make it easier to understand what is Moritz and what is Doxygen. The use of Code::Blocks is not mandatory part of the tutorial. But since using tools like Moritz and Doxygen means to extend comments inside the sources the use of an IDE is helpful. Nevertheless if the use of a very simple text-editor to take a look into the sources is also possible. Later it will be necessary to compile the sources and derivatives of them, thus you need a compiler also and the knowledge how to use it also. In the case you decide to use Code::Blocks please refer the associated home-page and its wiki to learn where to get the IDE the compiler and how to install it.

The Example Sources

The folder “src” that contains the source-example has 3 sub-directories:• component :

1. contains the layer structure as described above • stimulation :

1. contains a using application that calls the interface-layer2. in some tutorials it contains special test-sources also

• simulation : 1. contains a simple replacement of the micro controller files2. in some tutorials it contains a simple mechanical simulation also

Please explore the content of all folders to learn where the files are located. Especially for a beginner in programming C or C++ it is very essential to understand that the whole source-code is divided in Modules and every module contains one c file and one h file. While the c files contain allparts which define memory-objects what means the global variables of the module and the function-bodies the h files contain the prototypes and declarations also necessary for using sources outside ofthe module.

Global variables of a module are variables outside of the functions but only known by the module itself. Without using an extern declaration inside other sources a compiler error will be the result of the trial to access a variable outside of its module. Only functions declared in the h file of the module could be used to read the content or to write into it. Even the example-sources are c-files you could compare a module with a singleton class where the functions are the methods and the module variables are the private attributes.

The only exception is the module “controller” in the sub-folder “simulation”. Here already the h filecontains extern declarations of the module variables. This is necessary since this variables are the special function registers of the micro controller. Thus they are known by the compiler used to buildthe binary for the controller and have to be known by the pc compiler in the same way.

Since the character of the h files is more informative they contain the special comments used for Doxygen also. Especially in the case the c or cpp files are not available anymore since their contentwas transferred into a library, the h-files are still used and together with them the describing comments of the module.

The Moritz Configuration

In the sub folder “Moritz/cfg” 3 xml-files may be found:

• ansi_c_abc2xml_cfg.xml : • configuration of abc2xml to parse the sources

• ansi_c_xml2abc_cfg_nsd.xml : • configuration of xml2abc to create nassi shneiderman diagrams

• ansi_c_xml2abc_cfg_uad.xml :• configuration of xml2abc to create UML like activity diagrams

In the documentation of Moritz a detailed description of the configuration can be found in the chapter “Using the configuration-files of abc2xml and xml2abc ”. Thus here only some project depending configurations should be explained here:

ansi_c_abc2xml_cfg.xml

<Source>  <FolderName value="../src/" root="SourcePath" fileAttachment=".c" recursive="Yes" doNotSkip="No">  <Common name="Common" keepValideCode="Implicit"/> </FolderName> </Source>

Since all c sources should be analyzed in the section “Source” only one folder-name is defined. Since the value of the tag “SourcePath” in the section “Path” is empty the attribute root can be ignored. The attribute “fileAttachment” defines that only files with the attachment “.c” should be used. The attribute “value” defines only a root-folder but all c-files in its sub-folders should be analyzed also, thus the attribute “recursive is set to “Yes”.

Since the sources may contain preprocessor directives the attribute “doNotSkip” has currently no meaning but may be used in later versions to save time by skipping the analysis of unchanged sources. But for the directive process of the parser at least a common set of definitions has to be set in this case the definition set “Common”. Furthermore it should be tried to solve compiler switches implicit what means once a preprocessor constant is not defined in the chosen definition set it will be treated as undefined.

<DirectiveDefinition>  <Variant name="Common">   </Variant> </DirectiveDefinition>

This is the associated definition set what is currently commented out.

<Path>  <DestinationPath value="./xml/" />  <User>

 <SourcePath value="" />

 <LangPackPath value="[?(#Configuration/UserArgument/RootPath)!({value})]/" /> </User> </Path>

In the section “Path” two important definitions are done on the one side the destination for the generated xml-files are is set as the folder “xml”. On the other side in the sub-section “User” the root-folder of the language-package to use is defined. But here a new feature is used to enable the use of a application argument instead of putting this definition directly into the xml-file. With the version Moritz 2.0.2 the binaries provide the possibility to use self defined user arguments which will be added as an own section “UserAguments” directly under the root node “configuration”. Every user argument contains a keyword that defines the tag in this case “RootPath” and a value added as attribute “value”.

ansi_c_xml2abc_cfg_nsd.xml and ansi_c_xml2abc_cfg_uad.xml

<Source>

 <FolderName value="./xml/" root="SourcePath" fileAttachment="_c.xml" recursive="No" doNotSkip="No"/>

<NotUsed>

 <FileName value="./xml/Doxygen/index.xml" root="SourcePath" doNotSkip="No"/> ● ● ●

</NotUsed>

</Source>

Since all xml sources should be analyzed in the section “Source” only one folder-name is defined. Since the value of the tag “SourcePath” in the section “Path” is empty the attribute root can be ignored. The attribute “fileAttachment” defines that only files with the ending “._c.xml” should be used what means xml files with names not ending with”_c” will not be analyzed. The attribute “value” defines only a root-folder and files in its sub-folders should not be analyzed, thus the attribute “recursive is set to “No”.

Even the tag “NotUsed” is not defined as official part of the configuration it is used in this example.But as the name tries to describe its content will not be used. But it should be provided for a later step.

<Path>

 <DestinationPath value="./dot/" />

 <SourcePath value="./" />

 <LangPackPath value="[?(#Configuration/UserArgument/RootPath)!({value})]/" />

</User> </Path>

In the section “Path” two important definitions are done on the one side the destination for the generated xml files are is set as the folder “nsd” or “dot” depending on the scripts to generate. On the other side in the sub-section “User” the root-folder of the language-package to use is defined. But here a new feature is used to enable the use of a application argument instead of putting this definition directly into the xml file. With the version Moritz 2.0.2 the binaries provide the possibility to use self defined user arguments which will be added as an own section “UserAguments” directly under the root node “configuration”. Every user argument contains a keyword that defines the tag in this case “RootPath” and a value added as attribute “value”.

Create Script

To run the Moritz binaries a command script is used depending on your operation system this may be a windows batch or a shell script. Unfortunately the used commands differ a little bit thus please refer to the help system of your computer for details.

This is the windows example:

rem delete results of older runs del .\xml\*.xml del .\des\*.html del .\nsd\*.html del .\nsd\*.xml del .\dot\*.dt del .\dot\*.c

rem call the script that defines the used environment variables call ..\path_def.bat

rem call abc2xml for creating the xml parser trees %Moritz_PATH%\bin\abc2xml UA:RootPath=%Moritz_PATH% CF.\cfg\ansi_c_abc2xml_cfg.xml >log_abc2xml.txt rem pause

rem call xml2abc for creating the nassi shneiderman diagrams %Moritz_PATH%\bin\xml2abc UA:RootPath=%Moritz_PATH% CF.\cfg\ansi_c_xml2abc_cfg_nsd.xml >log_xml2abc_nsd.txt rem pause

rem call xml2abc for creating the uml like activity diagrams %Moritz_PATH%\bin\xml2abc UA:RootPath=%Moritz_PATH% CF.\cfg\ansi_c_xml2abc_cfg_uad.xml >log_xml2abc_uad.txt rem pause

1. In the first section older results will be removed (the corresponding shell command is rm instead of del).

2. Then the path_def script will be called that defines the used environment-variable “Moritz_PATH” (the corresponding shell command is a single dot with a white-space behind instead of call)

3. Now the binaries could be started. The used environment variable “Moritz_PATH” defines the root folder of the Moritz distribution (in a shell script an environment variable will be setin “$(“ and “)” instead of “%”). Thus it is used to extend the path “bin” of every call. Please remember the binaries are not installed and not known by your operation system. Therefore it is easier to switch between different versions of Moritz just by changing the content of your path_def script. Every binary gets two arguments:

1. UA:RootPath=• Here the Environment-variable for the root-folder of the Moritz distribution

will be used as value also. The reason is that here are some additional configuration-files are located in the sub-folder “LangPack”. For some reasons in a bigger project the tool-maintainer may decide to change this structure and than the value has to be changed

2. CF:• Here the user-configuration will be used with a pat relative to the location of

the create script.

Note a shell script starts always in the first line with:#!/bin/bash

On a Linux system it has to be configured as an executable script. Depending on your Linux distribution it may be also necessary to do some more configurations to run in from the GUI interface (X Server) as well as from the terminal.

Running Moritz

Once the Moritz distribution is running and the path_def script is updated the create script should already work without changing its content. In the case that there are some doubts the pause commands may be activated by removing the rem before (in shell scripts the command pause has tobe replaced by read and rem by # ). Now the terminal opened by starting the create-script will not be closed until the return or enter key will be pressed and it will be possible to explore error-messages created by the operation system.

The most probably message will complain that the binaries are not existing what means that the definition of the environment-variable “Moritz_PATH” is not valid. Note, while in the xml configuration the path separator is usually a slash (/) even in windows in a windows batch script the path separator is always a backslash (\) while Linux is using a slash (/) instead.An other reason may be that relative path definition is not valid since the path_def script location differs from the location of the create script. It is better to use an absolute path.

In the case that there are no error-messages in the terminal window but the binaries terminate without creating the expected result the generated log files may contain some more information. Butin this case it may be better to use the forum of the Moritz project to discuss this details. Once the create-script has finished its job without errors 3 new sub folder are existing now (if they where not already available before):

• xml: the output folder of abc2xml• nsd: the output folder of xml2abc while creating nassi shneiderman diagrams• dot: the output folder of xml2abc while creating uml like activity diagrams

Furthermore parallel to the create-script 3 text-files will be existing since the create-script contains by-pass commands used with the calls of the Moritz binaries to store their terminal-outputs into text-files. Usually this files contain a lot of debug-outputs that may be useful in the case of errors thus it should be not discussed in this tutorial. But while discussing problems in the forum it may behelpful to attach this text files to the post.

The files generated by Moritz

XML

The folder xml contains the parsing results every analyzed source file will be transferred into an xml file. The name of the xml is the name of the source wile the dot between the name and the attachment will be replaced by an underscore ( _ ) .

The content of the xml file is very huge and may look a little bit confusing. For example if the source file contains this function only

TYPE modell_CommentsBehind__function(TYPE Parameter)// this is the modell of a function// with comments behind of the commands{ TYPE ReturnValue; //comment ReturnValue TYPE_A LokalVariable_1 = Value1; //variable-comment 1 TYPE_A LokalVariable_2; //variable-comment 2 TYPE_Z LokalVariable_N = ValueN; //variable-comment N Operation_1( & LokalVariable_1,Parameter); //operation-comment 1 LokalVariable_2 = operation_2(LokalVariable_N); //operation-comment 2 if(LokalVariable_1 == LokalVariable_2) //statement-comment for true { ReturnValue = DefaultValue; //operation-comment for true } Else //statement-comment for false { while(ParameterStatment) //loop-comment ReturnValue = operation_3(); //operation-comment 3 }; return(ReturnValue); //comment return-line}

The resulting xml content will use more than one page of this documentation thus it will be shown on the next page only reduced wile the dots replace some ore pages. It is not part of this introduction to explain the whole content of the parser-result but it may be usefull to compare the xml content with the original source-code. At he end the xml-file contains the complete source but not in an document orientated form. The tags used in the xml file symbolize the parsing-rules used by abc2xml. Since the rules are nested the result is a tree structure and only the leaf nodes contain the associated source-parts. The attributes “L” and “C” are used to store line and column of the parsing results in the original source text wile the attributes “H” and “W” are used to store high and width of block comments.

Since the parser result should be used for the purpose of source documentation it containsnot only the active code but the comments also.

<function_definition L="10" C="1"> <declaration_specifier L="10" C="1"> <USER_TYPE L="10" C="1"> <ID L="10" C="1">TYPE</ID> </USER_TYPE> </declaration_specifier> <declarator L="10" C="6"> <direct_declarator L="10" C="6"> <ID L="10" C="6">modell_CommentsBehind__function</ID> <direct_declarator_second L="10" C="37"> <direct_parameter_declarator L="10" C="37"> <KeyChr L="10" C="37">(</KeyChr> <parameter_type_list L="10" C="38"> <parameter_list L="10" C="38"> <parameter_declaration L="10" C="38"> <declaration_specifier L="10" C="38"> <USER_TYPE L="10" C="38"> <ID L="10" C="38">TYPE</ID> </USER_TYPE> </declaration_specifier> <declarator L="10" C="43"> <direct_declarator L="10" C="43"> <ID L="10" C="43">Parameter</ID> </direct_declarator> </declarator> </parameter_declaration> </parameter_list> </parameter_type_list> <KeyChr L="10" C="52">)</KeyChr> </direct_parameter_declarator> </direct_declarator_second> </direct_declarator> </declarator> <Comment L="11" C="1" H="2" W="39">// this is the modell of a function // with comments behind of the commands</Comment> <compound_statement L="13" C="1"> <KeyChr L="13" C="1">{</KeyChr> <declaration L="14" C="2"> <declaration_specifier L="14" C="2"> <USER_TYPE L="14" C="2"> <ID L="14" C="2">TYPE</ID> </USER_TYPE> </declaration_specifier> <init_declarator L="14" C="9"> <declarator L="14" C="9"> <direct_declarator L="14" C="9"> <ID L="14" C="9">ReturnValue</ID> </direct_declarator> </declarator> </init_declarator> <semikolon L="14" C="20">;</semikolon> <Comment L="14" C="46" H="1" W="21">//comment ReturnValue</Comment> </declaration> ● ● ● <KeyChr L="34" C="1">}</KeyChr> </compound_statement> </function_definition>

NSD

The folder nsd contains the nassi shneiderman diagrams generated by xml2abc. The used file formatis html and the diagrams are nested html tables. Thus it is possible to open the files with a normal html browser like the Firefox to see the diagrams.

For every source file one collection of all contained functions will be generated. Furthermore for every function an additional diagram file is existing in a later tutorial it will be shown how to integrate them into the source documentation generated with Doxygen.

DOT

The folder do contains the uml like activity diagrams generated by xml2abc. The used file format is the dot script language. Thus it is not possible to open the files with a normal html browser like the Firefox to see the diagrams. But together with the dot binary the Graphviz package contains the gui tool “gvedit” that can be used to view the resulting diagram without running dot before.

Compared to nassi shneiderman diagrams activity diagrams take more size. In a later tutorial it will be shown how special commands can be used to exclude part-diagrams. In addition to the dot-scripts the folder nsd contains for every original source file a associated c file. But this contains only some special Doxygen comments. in a later tutorial it will be shown how to integrate them into the source documentation generated with Doxygen.

The Doxygen Configuration

The documentation of Doxygen is very detailed and and available with every new version at the associated web locations. Thus this tutorial has not the goal to replace it. But it should show how to combine the use of Doxygen and Moritz.

How ever in the introduction there is no connection between Doxygen and Moritz. Never the less there are some points to recognize since the may be a little bit special for some people.

The Doxygen sub folder “texts” contains additional texts which are used for those pages and chapters which may overcharge a single source text. Since Doxygen needs always comments to recognize a text this text-files contain c block-comments with Doxygen extensions. But actually files with the extension “.txt” are not evaluated by Doxygen thus it is necessary to extend 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”.

The Doxygen sub folder “pictures” contains image files used in the Doxygen output. Thus this path has to be inserted in the list “IMAGE_PATH” of the Doxygen configuration. Note depending on theoutput-format of Doxygen the use of the special command “image” differs, thus pleas refer the Doxygen documentation for details.

Since Doxygen should use external tools like dot or the html workshop (only available for windows) Doxygen needs to know where this tools are located. Since this information is already defined in the path_def script it is a good practice to use for path-definitions the associated environment variables.

In Doxygen an environment variable will be framed with “$(“ and “)” like in this example:

DOT_PATH = $(DOT_PATH)

The “DOT_PATH” on the left side is the configuration constant defined by Doxygen, while the “DOT_PATH” on the right side is the name of the environment variable used in the path_def script. It is essential to call the script together with Doxygen or the doxywizard. And the best way to do so is to use a command script for this like this windows batch example:

call ..\path_def.bat

call %DOXY_PATH%\doxywizard.exe Doxyfile_Introduction

Note, under Linux a dot ( . ) has to be used instead of “call”, the path separator is a slash (/) instead of a backslash (\) and the environment variable is framed by ( $( ) and ( ) ) instead of (%). By usingthis two commands inside a script the definitions inside the called path_def script are still valid if the doxywizard is active. Once the doxywizard will be closed the command script will be closed and the definitions done by the path_def script are not present anymore. Unfortunately there is currently now way to define for the doxywizard where Doxygen is located what means Doxygen and the doxywizard have to be installed regularly to enable the start of Doxygen with the doxywizard.

While the analyzed sources and additional text files contain special Doxygen commands to control the content of the documentation a special configuration file is used to control the behavior of Doxygen. Since Doxygen comes from the Linux world the file has for traditional reasons no file attachment. But it is a normal text-file that can be opened and modified not only with the doxywizard but with a normal text-editor also. To run Doxygen without the doxywizard the command script mentioned above can be used if the identifier “doxywizard” will be changed into “doxygen”.

The Documentation generated by Doxygen

The tutorial is using only the file format html since this file format is easily to explore while other file-formats may need some additional tools like a latex compiler. Furthermore are some files included in the documentation only usable for html (for example the nassi shneiderman diagrams).

Once Doxygen has finished its work the file “StartDoc.html”, located in the Doxygen folder, can be used to open the created documentation. Otherwise the file “index.html” inside the Doxygen sub folder has to be used and opened.

The main page contains the description of the example project. Depending on the security configuration of the html browser on the left side an additional navigation tree may appear. If not onthe top of the page some tabs can be used to navigate.

In the basic version of the example documentation the tabs “Modules” and “Files” are available parallel to the “Mainpage”. While the file documentation reflects the folder-structure of the example, the modules reflect the grouping structure defined by the Doxygen grouping commands.

A detailed look to the function documentation shows that in the basic documentation only those features are used which are provided by Doxygen itself (note, this is only the case if the comment ismarked to be evaluated by doygen refer the Doxygen manual for this):

• The normal text content of the function comment will be displayed as description

• The special commands “param” and “return” are used to document the data-interface of the function.

• Since Doxygen comes along with an own c parser it is able to recognize other source elements used in a function-body. This makes it possible to provide lists of used elements and using functions. Once the dot tool is available call and caller graphs will be created toshow the dependency between the function and other functions (used or using)

Since Doxygen is originally developed to document libraries for other programmers a detailed information how the function works internally will not be provided. The only possibility is to activated the source browsing option “INLINE_SOURCES”, what will include the body source of the function.

And here Moritz will start to help. With Moritz it is possible to expand the documentation with :

• Nassi Shneiderman Diagrams

• UML like activity diagrams

• Message Sequence Charts

Furthermore it is possible to support software tests by generating special source-files to replace usedmodules by “Stub-Modules” or extended sources which contain “Probe-commands” to observe the internal behavior while a single test.

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/

http://sourceforge.net/projects/moritz/

http://CodeBlocks.org/

http://www.mcternan.me.uk/mscgen

http://www.graphviz.org/

http://www.Doxygen.org/

http://sourceforge.net/projects/mulanpa/

tutorial for moritz · • message sequence charts ... opening the file “startdoc.html”. the...

Documents