This page gives some basic information on how to use the FW Profile Design Documentation Generator. The Generator is a tool that makes it possible to keep the model documentation as up-to-date as possible (and always in sync with the model) by allowing the designer to write the documentation into the model itself as comments to various UML2 elements. Then the model documentation can be generated as a set of HTML pages in Javadoc-like fashion.

Documentation Generator Overview

The model documentation is stored in the UML2 model itself as

• Comment UML2 elements that can be added to virtually any UML2 elements.
• UML2 diagrams, namely
  • Class Diagrams and
  • State Machine Diagrams

The documentation is extracted in several steps as illustrated in the following picture. The tools are red while the data are blue:

The documentation generation is made in the following steps:

1. A valid UML2 model that conforms with the FW Profile is the input of the Generator.
2. Model-to-text transformation implemented in MOFScript language is applied to the UML2 model and generates Java source files
3. Set of Java source files contains Javadoc comments which were extracted from the UML2 Comment elements
4. Javadoc tool (part of the Java Standard Development Kit) is used to generate HTML documentation from the Java source files
5. Set of HTML files contains all the text comments from the Java source files (and hence from the model) as well as links to UML2 diagrams which are stored as pictures and references from the comments with IMG element of HTML.
6. Ant tasks are used to replace or delete unwanted Java-specific texts from the HTML pages generated by Javadoc tool
7. Set of HTML files contains the design documentation.

The above sequence of actions is implemented in the com.pnp.fwprofile.docgen plug-in distributed with the FW Profile. The tool (2) is implemented as a MOFScript file uml2java/uml2java.m2t and tools (4) and (6) are implemented as Ant build files javadoc.xml.

Supported UML2 Comments in the UML2 Model

The following are UML2 elements whose comment are processed by Documentation Generator tool.

• Interface elements
• Class elements
• Attribute elements
• Operation elements including constructors and trigger operations
• OpaqueBehavior elements linked to Operation elements

Comments that are attached to other UML2 elements are ignored by the tool.

FW Profile defines so called FW Profile Action Language. It is possible to describe behavior of operations using this language. Such behavior is specified in the Body attribute of the OpaqueBehavior element and is linked with the Operation element using respectively Specification and Method attributes. If an operation has behavior specified in action language, the action language code is included in the generated documentation.

Including UML2 Diagrams to the Generated Documentation

It is possible to include the class diagrams and state machine diagrams to the documentation. An example of this may be the Component class documentation where the state machine diagram is shown. The class diagrams may be added to the documentation following these steps:

1. Open the diagram in the Topcased UML Modeler
2. Right-click the diagram and choose "Export to file" in the pop-up menu
3. Save the file to dedicated folder, for example img is used in the com.pnp.cordet.design project. Name the file e.g. SM_Component.png.
4. Start writing the documentation of the Component class. This will be written to the Body attribute of the Comment subelement of the Component's Class element.
5. Write the @image SM_Component.png at any place in the comment; the Documentation Generator will automatically replace the string with something like <center><img src="../../../../../img/SM_Component.png"/><br/>SM_Component.png<br/><br/></center>.

Note that not only class diagrams and state machine diagrams may by included in the comments. It is possible to store any other image (and in any format) in the img directory and reference it using @image tag.

The MOFScript Generator

The first step in the Documentation Generator tool chains is the model-to-text transformation. The transformation is implemented in MOFScript language. One single file uml2java.m2t implements the transforamtion.

The file is located in the uml2java directory of the com.pnp.fwprofile.docgen plug-in distributed with FW Profile.

To execute the generator the MOFScript Eclipse plug-in is required. The plug-in is available from http://modelbased.net/mofscript/ .

To execute the generator, open the uml2java.m2t file and click "Execute Model 2 Text" button in Eclipse toolbar. Then locate the UML2 model (e.g. CordetDhAndAocsFw.uml) and click the "Open" button. You may wish to see the processing messages of the MOFScript processor in the Console view.

The files are generated to the location which specified in the Eclipse Preferences item "Root Generation Dir". It is recommended to change the location of the generated code by right-clicking the uml2java.m2t file and choosing Properties | MOFScript Properties | Select Root Output Directory. Set the output folder to the src subfolder of the com.pnp.fwprofile.docgen installation directory.

The Ant Script

The second and third steps in the Documentation Generator tool chains are the Javadoc generation and postprocessing of the generated HTML pages. The is controlled by an Ant script javadoc.xml located in the com.pnp.fwprofile.docgen plugin.

By default, the Java source files are expected in the src subfolder of the com.pnp.fwprofile.docgen plug-in. The destination folder where the HTML files are to be generated is by default doc subfolder of the com.pnp.fwprofile.docgen plug-in. Both folders can be changed in the Ant script.