Documentation templates

 

Introduction to documentation templates

Documentation templates are used to develop document models, which can be applied to UML models. Each documentation template concentrates on a specific metaclass belonging to the metamodel referenced by the MDA component.

 

Documentation template design can be a difficult task: defining a typical tree hierarchy, adapted to any model variation, not too wordy, but providing clear and pertinent information to those reading the documentation.  To obtain the required document, you must already have an idea of the structure, before improving its form.

 

Documentation templates are structured using production nodes and navigation nodes.

 

 

Creating a documentation template

To create a new documentation template, click on the  icon from a profile implementation. The “Documentation template” window then appears (for details on this window, see “General principles of template design”).

 

Figure 157. The documentation template editor

 

 

Toolbar

On the top-right of the template design window, the icons (which are presented on the top-right of the template design window as shown in Figure 157) available on a documentation template to create nodes are detailed below.

 

Icon

Description

This icon is used to create a navigation node. It is available on the template root, on a navigation node or on a production node.

This icon is used to create a production node. It is available on the template root, on a navigation node or on a production node.

This icon is used to reference an internal node in order to execute an existing node. It is available on the template root, on a navigation node or on a production node.

 

 

Documentation template properties

The properties specific to documentation templates are as follows:

Property

Description

Page header

The content of the page header ($TITLE, $AUTHOR, $REFERENCE, $VERSION, $DATE, \PAGENUM\).

Page footer

The content of the footnote ($TITLE, $AUTHOR, $REFERENCE, $VERSION, $DATE, \PAGENUM\).

Table of content

The automatic insertion of a table of contents.

 

 

Adding a navigation node

Navigation nodes are elements which belong to the profile's reference metamodel. Examples of navigation nodes could be the “Package”, “Class” or “Operation” metaclasses. A “Package” navigation node would browse all the packages belonging to a given package, while a “Class” navigation node would browse the classes belonging to the package in question. An “Operation” navigation node would browse all the operations belonging to a given class.

 

To add a new navigation node to your diagram, code or documentation template, simply click on the  icon on the top-left of the template design window and select the type of UML element you wish to retrieve using the scan method (Figure 158).

 

Figure 158. Creating a navigation node

 

Steps:

1.      Click on the  icon. The “Selection of a scan method” window then appears.

2.      In this window, select the element you wish to scan for. Elements of the indicated type will be retrieved by this method. In our example, the scan method will return the classes belonging to a package.

3.      Click on “OK” to confirm.

 

If you want to create a node without navigating to another element, select “Retrieve the current element” in the previous dialog box.

 

 

Navigation node properties

The properties of a navigation node are presented on the top-right of the template design window, when a navigation node has been selected, as shown in Figure 159.

 

Figure 159. The properties of a navigation node

 

Property

Description

Scan method

This property corresponds to the method used on the current element to obtain its sub-elements. In the example shown in Figure 159 above, the current element is an actor and the “OwnedElementActor” method is called to retrieve the actors belonging to this actor.

Metaclass

This property indicates the metaclass returned by the scan method.

Filter

This property is used to filter elements according to their stereotypes, tagged values, notes or properties.

Triggered action

This property indicates code to be executed for each element scanned by the scan method. For example, traces can be displayed.

This property is not available for code templates.

Memorize

This property is used to memorize the elements that are browsed by the navigation node. This field must contain a character string representing the name of the element to retain. This name can then be used to retrieve the memorized element.

Header

This property defines the text to be inserted before the generation of all the model elements the navigation node browses.

Title

This property defines the text to be inserted before the generation of all the model elements the navigation node browses.

Chapter

This property indicates the generation of a chapter, when the tickbox is checked.

Presentation

This property defines the type of presentation for the generated items (bulleted list, item, group).

Added to index

This property indicates that the element is added to the index and the explorer of the generated document.

Generate in a file

This property indicates the generation in a file of the model element the navigation node browses, when the box is checked. This tickbox is used only for HTML format generation. For other formats, it is ignored.

Partial generation

This property indicates the permission for the navigation node to carry out partial generation, when the box is checked. If the box has been checked, the navigation node will appear in the "Partial generation" tab of the document work product.

 

 

Modifying a navigation node

After adding a navigation node, you can modify the J code defined in the “Scan method” property, for example, to add a filter.

 

For example, instead of “OwnedElementClass”, you can replace by “OwnedElementClass.<select (IsAbstract)” to retrieve only the abstract classes.

 

For more information on entering J code, please see “Inserting J code”.

 

 

Adding a production node

To add a new production node to your documentation template, simply click on the  icon and then define the production node you wish to create.

 

 

Modifying the properties of a production node

Production node properties differ according to the document item selected.

 

Production nodes have one property, "Value", for which the value can be directly parameterized and which can contain a J function.

 

The contents of a property must appear between inverted commas, if they are not J code. For example, to display the name of a navigation node preceded by the “Name” string, the following should be entered: "Name: " + Name.

 

For more information on entering J code, please see “Inserting J code”.

 

 

Inserting a diagram

Despite the fact that they resemble a navigation node, diagrams are primarily used as images. This means that in order to insert the image of a diagram, both these nodes must be used.

 

Let us imagine that we want to insert into our documentation the class diagrams belonging to the current package.

 

Figure 160. Creating the "Class diagrams" navigation node

 

Steps:

1.      Select the documentation template.

2.      Create a navigation node to retrieve the diagrams of the current package. For more information on creating navigation nodes, please see “Creating navigation nodes”. Click on the  icon on the top-left of the window and select “Class diagrams” from the possible navigation nodes.

3.      Click on "OK" to confirm creation of this navigation node.

 

Continue with the steps shown in Figure 161.

 

Figure 161. Inserting a diagram

 

1.      Select the "Class diagrams" navigation node.

2.      Click on the  icon.  The new production node then appears.

3.      Select the production node.

4.      On the right-hand side of the window, click in the "Value" field associated with the "Value" property, and when the field is active, click on the  button.  The "Property modification" window then appears.

5.      In the "Property modification" window, open the "Services" folder and double-click on the "getIncludeFile" service.

 

 

Using a documentation template

In order to use a documentation template you have just developed, you must first have carried out the following operations:

·         Compile and package the MDA component that contains your documentation template

·         Deploy this MDA component in your project

 

We are now going to create a document work product and select the MDA component that this work product will use (Figure 162).

 


Figure 162. Creating a document work product


Steps:

1.      Select a package in the explorer.

2.      Click on the  "Create a generation work product" icon.

3.      Select the MDA component that contains your documentation template.

4.      Click on "OK".

 

The window shown in Figure 163 then appears.

 

Figure 163. The document work product definition window

 

Steps:

1.      Define the values for your document work product.

2.      Select your documentation template.

3.      Confirm by clicking on "OK".

 

 

Generating and visualizing the document

The document work product can now be generated like any other work product, and the result can be visualized.  For more information, please see "Documentation User Guide".