Generation of Interface Documentation
The generator of interface documentation takes an interface model (.interface file), the relevant interface signature model, a MS Word template as input and generates MS Word document according to the template. The generated document includes descriptions of user-defined types, commands, signals, notifications, state machines, and constraints. The generated documentation also includes the UML diagrams of state machines and constraints.
The users need to provide descriptions of interface elements as comments in the models placed before the elements. The following example shows comments for an interface and a command that will be included in the generated document:
/* The example ICamera interface defines signatures of commands and notifications supported by a digital camera. */ signature ICamera commands /*Turns on the camera. Returns a value of type Status.*/ Status PowerOn
The CommaSuite framework provides a predefined template for documenting interfaces.
To generate interface documentation, follow the steps below:
-
Load the predefined template. Right mouse button click on the project file (.prj) shows a context menu. Select Import Documentation Template.
-
In the project file, define a documentation generation task. The following example shows a documentation generation task for the camera interface:
Generate Documentations { docTask for interface ICamera { template = "Template.docx" //Give the name of the documentation template targetFile = "result.docx" //Give the name of the result file author = "John Smith" //Give the name role = "Designer" //Give the role } }
-
Execute the generation tasks by choosing Run As → Run generators from the context menu. The generated MS Word file is located in the subfolder src-gen/doc.
You may need to manually update the table of contents and the size of the pictures.