SRRC Wiki

Service Robotics Research Center
at Ulm University of Applied Sciences

User Tools

Site Tools


how-tos:documentation-datasheet:start

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
how-tos:documentation-datasheet:start [2019/12/10 11:45]
Alex Lotz
how-tos:documentation-datasheet:start [2019/12/12 17:43]
Dennis Stampfer
Line 30: Line 30:
 {{ :​how-tos:​documentation-datasheet:​cdlparametersdocumentation.png |}} {{ :​how-tos:​documentation-datasheet:​cdlparametersdocumentation.png |}}
  
-Here you can see parameters of the CDL component are documented individually using the same comment-like syntax. As can bee seen not all element strictly ​have to be documented (although we highly recommend to do so), and you don't have to use multiple lines for documentation,​ single line comments are fine as well.+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,​ single line comments are fine as well.
  
  
 ===== Adding further Non-technical Meta-Data Elements to the Component Model ===== ===== 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,​ yet structured documentation for meta-data elements such as e.g. the used license, the manufacturer and other non-technical attributes. Please notice, that the **ComponentDatasheet** model now replaces the old Component Documentation model, which is even deactivated since the SmartMDSD Toolchain version 3.12.+Since SmartMDSD Toolchain version 3.12, the **ComponentDatasheet** has been refined such that it solely focusses on the non-technical,​ yet structured documentation ​and annotation ​for meta-data elements such as e.g. the used license, the manufacturer and other non-technical attributes ​(descriptive information,​ also semantic information). Please notice, that the **ComponentDatasheet** model now replaces the old Component Documentation model, which is even deactivated since the SmartMDSD Toolchain version 3.12.
  
 You can easily create a new **ComponentDatasheet** model as follows (see also the following screenshot):​ You can easily create a new **ComponentDatasheet** model as follows (see also the following screenshot):​
Line 59: Line 59:
 {{ :​how-tos:​documentation-datasheet:​componentdocumentationreadme.png |}} {{ :​how-tos:​documentation-datasheet:​componentdocumentationreadme.png |}}
  
-new more powerful modeling feature provides ​richer documentation capability for the following project types+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 nice side effect, the Readme.md file uses markdown syntax that is compatible with the [[https://​guides.github.com/​features/​mastering-markdown/​|Github markdown syntax]], so that the readmes are nocely renderred when uploading the projects to Github.
  
-  ​for **DomainModels** projects: ​**DomainModelsDatasheet** (file extension ​**.domainModelsDatasheet**+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.
-  * 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).+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 modelAfter 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.
  
-{{ :how-tos:documentation-datasheet:​commjoystickdocu.png |}}+The documentation ​of the **DomainModel** and **System** projects works analogously to the here presented **Component** documentation,​ with the only difference of the Datasheet file extensions which are analogously **.domainModelsDatasheet** and **.systemDatasheet**.
  
-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). 
  
-{{ :​how-tos:​documentation-datasheet:​newdomainmodelsds.png?​500|}}+===== Free Form Documentation =====
  
-You can now create a new DomainModels Datasheet as follows: +To describe ​and document ​the algorithm ​that you implemented ​in a componentcomponent behavioror anything ​that is not covered by the above means for documentation,​ proceed as follows:
- +
-  - Select the **model** folder of your current project in the **Model Explorer** view +
-  - Use the Eclipse menu: **File** -> **New** -> **File** +
-  - 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. +
- +
-{{ :​how-tos:​documentation-datasheet:​commbasicobjectsds.png |}} +
- +
-The documentation of the Component model works analogously to the DomainModelswith 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).+
  
 +  * Create a folder "​documentation"​ in your project root
 +  * 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/​ folder. Make sure to link to them via index.md
  
 ===== Acknowledgements ===== ===== Acknowledgements =====
how-tos/documentation-datasheet/start.txt · Last modified: 2019/12/12 17:43 by Dennis Stampfer