Service Robotics Research Center
at Ulm University of Applied Sciences

User Tools

Site Tools

This version is outdated by a newer approved version.DiffThis version (2019/12/10 10:51) is a draft.
Approvals: 0/1
The Previously approved version (2019/01/29 16:14) is available.Diff

This is an old revision of the document!

Annotation and Documentation via the Digital Datatsheet

A digital data sheet contains different sections; at least a technical section and annotations section for humans. The SmartMDSD Toolchain supports the technical digital data sheet via its models. Its support via annotations is currently distributed over several places as this technology is currently in migration.

The concept of annotations via a component documentation model to enrich a software component with descriptions for humans is described in:

  • [Stampfer2018] Dennis Stampfer. “Contributions to System Composition using a System Design Process driven by Service Definitions for Service Robotics”. Dissertation, Technische Universität München, München, Germany, 2018. Link
  • [Stampfer2016] Dennis Stampfer, Alex Lotz, Matthias Lutz, and Christian Schlegel. “The SmartMDSD Toolchain: An Integrated MDSD Workflow and Integrated Development Environment (IDE) for Robotics Software.” In: Journal of Software Engineering for Robotics (JOSER): Special Issue on Domain-Specific Languages and Models in Robotics (DSLRob) 7.1 (2016). ISSN 2035-3928, pp. 3–19. Link

The concept is illustrated in the figure below [Stampfer2018]: The technical (component) model and the non-technical annotations together provide information for dedicated use-cases. Note that “data sheet model” and “documentation model/DSL” are used as synonyms here. The figure below illustrates the documentation for humans. The RDF example below illustrates the import in a triple-store for semantic search. Another example is the interaction with other tools via the digital data sheet (see the interaction between SmartMDSD Toolchain and Groot).

Documenting the Component Model

Since SmartMDSD Toolchain version 3.12, the overall documentation is split into two main parts, one is the explicit digital datasheet model for non-technical properties (see the next section below) and the other is the implicit annotation of technical models (as described next).

For technical documentation, you don't have to create any new models, but rather directly document your model elements as part of the technical model itself. In order to better distinguish the documentation from the actial model elements and for a most intuitive experience, we have adopted the notion of doxygen-like code comments in our textual models. So in order to document any model element, just add a comment above a specific element. Here we distinguish between two types of comments. One is the multiline comment that looks like this:

At the top in the screenshot you can see the textual representation of the component model and as an example, the ouput port named JoystickServiceOut has a green comment above it. Please note the two asterisks after the slash /**. A comment with two asterisks at the beginning is interpreted as an intentional documentation element, while a regular comment with only one asterisk after the slash /* is interpreted as a regular comment that is entirely ignored by the model interpreter. Regular comments can be used for example to temporarily comment out parts of the model or write any other comments that are not related to the model or documentation. Please also notice, each model element can have zero or exactly one documentation element that must be placed above the element to document, but an arbitrary number of regular comments that can be placed anywhere in the model. Moreover, you can use simple HTML text formatting tags which are interpreted at multiple places for formating the documentation comments. Please further notice that the optional astersisks (at the left side of the comment) are later parsed away for the actual documentation, so you don't have to care about them too much, they mostly serve a cosmetic purpose and not related to the actual documentation.

Next, at the middle of the above screenshot, you can see the graphical diagram of the example component model with the selected output port JoystickServiceOut, whose properties are further shown at the botton of the screenshot within the Properties tab. There you can see the same comment and you can even directly modify its contents directly from the Properties tab. Please note that you still have to use the doxygen-like syntax as explained for the textual part above. Regardless of from which model editor (graphical or textual) you create the documentation elements, the respective other representation will be automatically synchronized as soon as you save the model.

In order to use the ComponentDocumentation feature in the SmartMDSD Toolchain, please manually create a new model file with the extension .componentDocumentation within the subfolder model of your component project. You can do this as follows:

  1. Select the model folder of your component project in the Model Explorer view
  2. Use the Eclipse menu: FileNewFile
  3. Provide the model file name, e.g.: SmartCdlServer.componentDocumentation (use your component name, but keep the file extension)

Your menu wizard should look as shown in the screenshot on the right.

Now you can provide the content of the ComponentDocumentation model as shown in the screenshot below. As soon as you save the ComponentDocumentation model, it will generate the file that uses the markdown syntax which can be interpreted by e.g. the github repository where this component might be hosted. For the SmartCdlServer example the output can be viewed here:

Please note that the ComponentDocumentation DSL is considered depricated and its features are currently being migrated to the Digital Datasheet Model (see next section).

Using the Digital Data Sheet Model

Since SmartMDSD Toolchain version 3.7, a new more powerful modeling feature provides a richer documentation capability for the following project types:

  • for DomainModels projects: DomainModelsDatasheet (file extension .domainModelsDatasheet)
  • for Component projects: ComponentDatasheet (file extension .componentDatasheet)

These DSLs are by themselves kept slim as they focus on describing non-technical metadata of the respective project and at the same time collect technical documentation directly from the respective technical models. As an example we will provide technical documentation for the CommJoystick communication object (see the following screenshot).

As shown in the screenshot above, you can document your model elements using a Javadoc-like syntax. Please note, that these comments are not only local comments, instead they are later collected from the respective Datasheed model to generate different Datasheet representations such as e.g. the RDF/TTL for importing in semantic triple-stores (as shown below).

You can now create a new DomainModels Datasheet as follows:

  1. Select the model folder of your current project in the Model Explorer view
  2. Use the Eclipse menu: FileNewFile
  3. Provide the model file name, e.g.: CommBasicObjects.domainModelsDatasheet (use your project name, but keep the file extension)

Your menu wizzard should look as shown in the screenshot on the right.

You can now provide the non-technical information such as e.g. the used License in this model file. As soon as you save the model, it will collect all the technical information from related models and non-technical information and generate the supported Datasheet types. At the moment we already support the RDF/TTL syntax for importing in semantic triple-stores. An example is shown in the screenshot below. Please note, that the previously defined comments from the CommJoystick are also reflected in the generated Datasheet syntax.

The documentation of the Component model works analogously to the DomainModels, with the only difference of the Datasheet file extension which is .componentDatasheet.

Please note, that the Datasheet feature will someday entirely replace the former “ComponentDocumentation” DSL (see above section).


how-tos/documentation-datasheet/start.1575971471.txt.gz · Last modified: 2019/12/10 10:51 by Alex Lotz