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 10:30]
Alex Lotz
how-tos:documentation-datasheet:start [2019/12/12 17:43] (current)
Dennis Stampfer
Line 22: Line 22:
 {{ :​how-tos:​documentation-datasheet:​componentdocumentationdemo.png |}} {{ :​how-tos:​documentation-datasheet:​componentdocumentationdemo.png |}}
  
-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 [[https://​www.w3schools.com/​html/​html_formatting.asp|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.+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 [[https://​www.w3schools.com/​html/​html_formatting.asp|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 are unrelated ​to the actual documentation.
  
-In order to use the ComponentDocumentation feature in the SmartMDSD Toolchainplease manually create a new model file with the extension **.componentDocumentation** ​within the subfolder ​**model** of your component projectYou can do this as follows:+Next, at the center of the above screenshotyou 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** tabThere you can see the same documentation comment and you can even directly modify its contents directly from the Properties tab. Please be aware that you still have to use the doxygen-like syntax with the %%/**%% tag 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.
  
-{{ :how-tos:documentation-datasheet:newfilefordocu.png?​500|}}+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:
  
-  ​Select the **model** folder of your component project in the **Model Explorer** view +{{ :how-tos:documentation-datasheet:cdlparametersdocumentation.png |}}
-  - Use the Eclipse menu**File** ​-> **New** -> **File** +
-  - 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.+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.
  
-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 README.md 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: 
  
-https://​github.com/​Servicerobotics-Ulm/​ComponentRepository/​tree/​master/​SmartCdlServer+===== Adding further Non-technical Meta-Data Elements to the Component Model =====
  
-{{ :how-tos:documentation-datasheet:​smartcdlserverdocuscreenshot.png |}}+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):​
  
-Please note that **the ComponentDocumentation DSL is considered depricated** and its features are currently being migrated to the Digital Datasheet ​Model (see next section).+  ​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...**
  
 +{{ :​how-tos:​documentation-datasheet:​newsmartmdsdmodelwizard.png |}}
  
 +A new popup window will appear where you will see the selected project. Please press the **Next** button so you should see this window:
  
-===== Using the Digital Data Sheet Model =====+{{ :​how-tos:​documentation-datasheet:​newcomponentdsmodelwizard.png |}}
  
-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**) +Here you should activate the checkbox ​for the **ComponentDatasheet** model type and press the **Finish** button to create the model in your projectIf 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**:
-  * 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).+{{ :how-tos:documentation-datasheet:​generatecomponentdocumentation.png |}}
  
-{{ :​how-tos:​documentation-datasheet:​commjoystickdocu.png |}}+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.
  
-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).+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. ​
  
-{{ :​how-tos:​documentation-datasheet:​newdomainmodelsds.png?500|}}+{{ :​how-tos:​documentation-datasheet:​componentdocumentationreadme.png |}}
  
-You can now create a new DomainModels Datasheet ​as follows:+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://​guides.github.com/​features/​mastering-markdown/​|Github markdown syntax]], so that the readmes are nocely renderred when uploading the projects to Github.
  
-  - Select ​the **model** folder of your current project in the **Model Explorer** view +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.
-  - 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.+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.
  
-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 modelit will collect all the technical information from related models and non-technical information and generate ​the supported ​Datasheet ​typesAt 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 **DomainModel** and **System** projects works analogously to the here presented **Component** documentationwith the only difference of the Datasheet ​file extensions which are analogously **.domainModelsDatasheet** and **.systemDatasheet**.
  
-{{ :​how-tos:​documentation-datasheet:​commbasicobjectsds.png |}} 
  
-The documentation of the Component model works analogously to the DomainModels,​ with the only difference of the Datasheet file extension which is **.componentDatasheet**.+===== Free Form Documentation =====
  
-Please note, that the Datasheet feature will someday entirely replace the former "​ComponentDocumentation"​ DSL (see above section).+To describe and document the algorithm that you implemented in a componentcomponent behavior, or anything ​that is not covered by the above means for documentation,​ proceed as follows:
  
 +  * 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.1575970251.txt.gz · Last modified: 2019/12/10 10:30 by Alex Lotz