Nassi Shneiderman Diagrams with Moritz and Doxygen Content

Nassi Shneiderman Diagrams with Moritz and Doxygen

This tutorial part describes how to create nassi shneiderman 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.

ContentNassi Shneiderman Diagrams with Moritz and Doxygen....................................................................1

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

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

Big functions will result in big diagrams ...................................................................................4Excluding function parts.............................................................................................................6

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

Linking Diagrams with the Documentation ..................................................................................15Configure Doxygen to create XML content with Link-References..........................................15Configure Moritz to evaluate the Doxygen XML Output.........................................................16

Other Diagram Modifications........................................................................................................17 Point out Sub Blocks........................................................................................................17Show the Original Source.........................................................................................................18 Independent Comment.............................................................................................................18

Resources and Links......................................................................................................................19

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 nassi shneiderman 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_nsd.xml : • configuration of xml2abc to create nassi shneiderman diagrams

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

The Doxygen Configuration

Since Doxygen should include the html files 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 “EXAMPLE_PATH” like this:

EXAMPLE_PATH = ../moritz/nsd

Note

• To update the content of the Doxygen an update Moritz has to be run first if the diagrams should be updated.

• Since nassi shneiderman diagrams will be generated as html files they can only be used if Doxygen should generate html output also.

Including single Diagrams

All nassi shneiderman diagrams generated by Moritz are located in the sub folder moritz/nsd. 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 including html files Doxygen provides the command “htmlinclude” 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 example-paths (EXAMPLE_PATH) 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

@htmlinclude regulator_c_F_moveTo.html*/ 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 nassi shneiderman diagram:

Please explore the example folder “NassiShneidermann_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 is still small enough to be displayed on one page it is already to huge to show all details clearly. Especially the if-expressions in the bottom part are extremely mashed and not easy to survey anymore.

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

Compared to the example without excludes here the if-expression is easy to survey.


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 html file is available, that looks 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 but the list of example paths in the “Doxyfile” has to be extended.

EXAMPLE_PATH = ../moritz/des \

../moritz/nsd

It is important to mention the sub path “moritz/des” before the sub path “moritz/nsd” since bot may contain files with the same name. And in this case Doxygen will take the first found file.

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 nassi shneiderman 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 html file is the same as the original source but its file-attachment is added with an underscore ( _ ).

Since this diagram-collections are html files also the Doxygen command “htmlinclude” has to be used again and if not already done it is recommended to add the file-location to the list of example-paths (EXAMPLE_PATH) in the “DoxyFile”.

But different to the diagrams of single functions it is better to add them as related pages by using the Doxygen commands “page” and “subpage” in addition.

The best way to add this pages is to have an additional text-file with the following content:/*!

@page DIAGRAMS Nassi Shneiderman Diagrams

@subpage diagrams_regulator_c

@subpage diagrams_measure_c

@subpage diagrams_gear_c

@subpage diagrams_voltage_c

@subpage diagrams_inswitch_c

@subpage diagrams_outswitch_c

*/

/*!

@page diagrams_regulator_c Regulator

@htmlinclude regulator_c.html

*/

/*!@page diagrams_measure_c Measure

@htmlinclude measure_c.html

*/

/*!

@page diagrams_gear_c Gear

@htmlinclude gear_c.html

*/

/*!

@page diagrams_voltage_c Voltage

@htmlinclude voltage_c.html

*/

/*!

@page diagrams_inswitch_c In-Switch

@htmlinclude inswitch_c.html

*/

/*!

@page diagrams_outswitch_c Out-Switch

@htmlinclude outswitch_c.html

*/

The first comment-block is used to create a root page:/*!

@page DIAGRAMS Nassi Shneiderman Diagrams

@subpage diagrams_regulator_c

@subpage diagrams_measure_c

@subpage diagrams_gear_c

@subpage diagrams_voltage_c

@subpage diagrams_inswitch_c

@subpage diagrams_outswitch_c

*/

This root page gets diverse sub pages for every diagram collection one.

For every collection one additional comment is used to create its associated page/*!



*/

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.

Once the file is saved it has to be added to the list of input-files in the “Doxyfile” :INPUT = ../src/component \

● ● ●

./texts/mainpage.txt \

./texts/addPages.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 html source of a description table:

<HTML>

<HEAD>

</HEAD>

<BODY>

<b> Details of Algorithm :</b>

<br>

<TABLE border="0" cellspacing="5" cellpadding="0">

<TR>

<TD align="left" valign="top">

<a href="diagrams_regulator_c.html#parkAtBegin"> parkAtBegin </a>

</TD>


<font color="#000000">repeat calling the regulation until destination or a time-out is reached</font>

</TD>

</TR>

<TR>


<a href="diagrams_regulator_c.html#parkAtBegin/next_regulation"> next_regulation </a>

</TD>


<font color="#000000">force moving backwards or stop moving depending on the remaining misplacement</font>

</TD>

</TR>

</TABLE>

</BODY>

</HTML>

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

/*!



*/

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


Linking Diagrams with the Documentation

Since the nassi shneiderman diagrams created by Moritz are HTML files it is possible to extent them with links back to the documentation parts generated by Doxygen. Therefore Doxygen has to provide xml-files which contain the anchor definitions used inside the html-files. Moritz is able to evaluate this xml files with its binary xml2abc to insert link-references of known source-elements into the diagrams. This is possible for single diagrams excluded part diagrams and for diagram collections.

Configure Doxygen to create XML content with Link-References

To force Doxygen to genrate xml-output the associated cofiguration tag “GENERATE_XML” has to be set to “YES”:

GENERATE_XML = YES

Furthermore Moritz expects the xml-files generated by Doxygen in an sub-folder of its own xml output-folder. Thus the Doxygen configuration tag “XML_OUTPUT” has to be modified:

XML_OUTPUT = xml/doxygen

Even this can be done by the modifying the already used “Doxyfile” it is better to create an onwn one directly in the moritz folder. To minimize the additional run-time and output all other output-formats should be switched of

GENERATE_HTML = NO

But it is still necessary to ensure that the sources are browsed completely thus set the associated configuration Tags to “YES”:

SOURCE_BROWSER = YES

REFERENCED_BY_RELATION = YES

REFERENCES_RELATION = YES

REFERENCES_LINK_SOURCE = YES

Once the new “Doxygfile” is stored in the folder “moritz” the create-script has to be modified: rem call the script that defines the used environment variables

call ..\path_def.bat

rem call doxygen to reate xml-files with link anchor information

%DOXY_PATH%\doxywizard Doxyfile_xml

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

It is essential to call Doxygen with the “Doxyfile” as argument before the Moritz binary xml2abc will be called. After Doxygen finished its work the sub folder “moritz/xml/doxygen” contains a lot of additional xml files which can be evaluated by Moritz for inserting links into the diagrams.

Configure Moritz to evaluate the Doxygen XML Output

Since the xml files generated by Doxygen differ very much from those generated by the Moritz binary abc2xml the distribution uses special x2a files (snippet definitions, please refer the the documentation of Moritz for details) to evaluate them. Fur the user configuration of xml2abc has to be extended:

<Source>



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



<FolderName value="./xml/doxygen/" root="SourcePath" fileAttachment="8cpp.xml" recursive="No" doNotSkip="No"/>



<FolderName value="./xml/doxygen/" root="SourcePath" fileAttachment="8c.xml" recursive="No" doNotSkip="No"/>



<FolderName value="./xml/doxygen/" root="SourcePath" fileAttachment="8h.xml" recursive="No" doNotSkip="No"/>



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

</Source>

Since the Moritz binary xml2abc evaluates the files in the order of the occurrence in the user-configuration it is important to add them over the already mentioned files. But not all files have to be analyzed. There is one central index file and for every source file an associated xml file where the dot between the file name and the file attachment is replaced by a ( 8 ). For convenient reasons the example contains “FolderName” configurations for the most occurring c/cpp sources even they are not all used in the example project. But his may be helpful once the example should be used as based for an own project. It should be no problem to copy and modify the line with “8cpp.xml” for analyzing hpp file results.

Once Doxygen has generated its xml output and the configuration of xml2abc is extended the output of Moritz already contains all possible links to other parts of the html documentation generated by Doxygen. Now it is not only possible to reach the diagrams in the collections it is also possible to reach the used source elements from the diagrams.

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

http://CodeBlocks.org/

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

http://www.graphviz.org/

http://www.Doxygen.org/

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

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

Nassi Shneiderman Diagrams with Moritz and Doxygen Content

Documents

Transcript of Nassi Shneiderman Diagrams with Moritz and Doxygen Content