how-tos:documentation-datasheet:start
Differences
This shows you the differences between two versions of the page.
— | how-tos:documentation-datasheet:start [2022/12/23 11:06] (current) – created - external edit 127.0.0.1 | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | ====== 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. " | ||
+ | * [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. [[http:// | ||
+ | |||
+ | The concept is illustrated in the figure below [Stampfer2018]: | ||
+ | |||
+ | {{ : | ||
+ | |||
+ | |||
+ | |||
+ | ===== 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, | ||
+ | |||
+ | {{ : | ||
+ | |||
+ | 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 **%%/ | ||
+ | |||
+ | Next, at the center of the above screenshot, you can see the graphical diagram of the example component model with the selected output port JoystickServiceOut, | ||
+ | |||
+ | The doxygen-like documentation capability is not limited to the component model, but is a recurring functionality in many other models as well. For instance, the component parameters can be documented in the same way as shown in the next screenshot: | ||
+ | |||
+ | {{ : | ||
+ | |||
+ | Here you can see the parameters of the CDL component (as an example) that are documented individually using the same comment-like syntax. As can bee seen not every element strictly has to be documented (although we highly recommend to do so), and you don't have to use multiple lines for documentation, | ||
+ | |||
+ | |||
+ | ===== Adding further Non-technical Meta-Data Elements to the Component Model ===== | ||
+ | |||
+ | Since SmartMDSD Toolchain version 3.12, the **ComponentDatasheet** has been refined such that it solely focusses on the non-technical, | ||
+ | |||
+ | You can easily create a new **ComponentDatasheet** model as follows (see also the following screenshot): | ||
+ | |||
+ | * Select a project in the SmartMDSD Project Explorer window at the left side of the Eclipse window | ||
+ | * Right click on the project and click at the context menu: **New** => **SmartMDSD Model...** | ||
+ | |||
+ | {{ : | ||
+ | |||
+ | A new popup window will appear where you will see the selected project. Please press the **Next** button so you should see this window: | ||
+ | |||
+ | {{ : | ||
+ | |||
+ | |||
+ | Here you should activate the checkbox for the **ComponentDatasheet** model type and press the **Finish** button to create the model in your project. If you now check the model folder of your project at the right side in the SmartMDSD Project Explorer, you should now see a new model with the file extension **.componentDatasheet**: | ||
+ | |||
+ | {{ : | ||
+ | |||
+ | Also, the component datasheet model will automatically open in the textual model editor as shown at the center of the above screenshot. Here you can add an arbitrary number of further custom **DatasheetPropert** elements. Each **DatasheetProperty** requires a **name** and a **value**. In addition, a **semanticID** and a **shortDescription** can be added. The **value** can be any string that makes sense in the context of the respective property. The **semanticID** is used to optionally reference an external specification of the property which can be e.g. an externally defined ontology, or any other taxonomy. | ||
+ | |||
+ | When you have provided all the required properties, you can now trigger the code generation (as shown in the above screenshot). Therefore, **select the project within the SmartMDSD Project Explorer** for which you want to trigger the code generator, and then use the Eclipse menu **SmartMDSD** => **Run Code-Generation**. This will generate two main outputs as described below. | ||
+ | |||
+ | {{ : | ||
+ | |||
+ | The code generation for the **ComponentDatasheet** model will generate two files, one is the **Readme.md** file that will collect all the technical documentation comments from all related technical models, as well as the non-technical properties from the datasheet model itself. You can vew the contents of the Readme by double clicking at it. Please don't modify the generated Readme.md file manually as all the manual changes will be whiped out the next time the code generation is triggered again. Instead you should provide the respective documentation directly within the models as described in the preceeding sections above and trigger the code generation again to update the Readme file. As a nice side effect, the Readme.md file uses a markdown syntax that is compatible with the [[https:// | ||
+ | |||
+ | The second output of the **ComponentDatasheet** model is the **.ttl** file located in the new **datasheet-gen** subfolder. This file uses the RDF/TTL syntax for importing in semantic triple-stores. We might add further output formats in the future releases of the SmartMDSD Toolchain. | ||
+ | |||
+ | Please notice, the documentation outputs are only generated if the respective project has a valid **ComponentDatasheet** model which acts as root model for code generation. This means that while you can (and should) provide technical documentation within technical models as described above, their output in the different datasheet formats will first take effect when you create a datasheet model. After that, you can modify any of the models as needed and the datasheet outputs will collect all the updates of all the models and re-combine them in the collective outputs. | ||
+ | |||
+ | The documentation of the **DomainModel** and **System** projects works analogously to the here presented **Component** documentation, | ||
+ | |||
+ | |||
+ | ===== Free Form Documentation ===== | ||
+ | |||
+ | To describe and document the algorithm that you implemented in a component, component behavior, or anything that is not covered by the above means for documentation, | ||
+ | |||
+ | * Create a folder " | ||
+ | * Place at least a index.md in that folder and put your documentation in markdown into that file | ||
+ | * Feel free to add any figures and further .md files to the documentation/ | ||
+ | |||
+ | ===== Acknowledgements ===== | ||
+ | |||
+ | {{ : | ||
+ | {{ : | ||
how-tos/documentation-datasheet/start.txt · Last modified: 2022/12/23 11:06 by 127.0.0.1