I spend a lot of time looking at Dymola models created by others, and a big factor in a model’s user friendliness is the quality of the documentation included. So in this blog post, I’m going to take a look at the documentation options available in Dymola.
Documenting Code
There are a number of ways you can include additional information in your models. The first I’m looking at, is documenting your code.
Figure 1 shows the code of a model which has been documented to make it easier to use and understand. Descriptions strings are highlighted in green. These should always be included for the model, variables, and components. These descriptions are displayed in:
- Parameter dialog boxes
- When hovering over a component in a diagram
- When selecting a change of class
It is also good practice to add comments to your code as you create it. Comments can be used to organise your code into sections to make it easier to navigate. They should also be used to describe the purpose of the calculations and perhaps where they have been referenced from. These comments provide context and making them more straightforward to understand.
Figure 1 – Documentation in the code of a model in the Dymola Text tab
Model Documentation
Detailed information about a model can be captured in the Documentation tab of the selected model. This included the information added by the model developer, as well as key information from the model code included automatically by Dymola. When writing documentation I typically include details of:
- The models purpose
- Any limitations or assumptions
- Instructions for use
- References to sources used
Figure 2 shows the documentation of the model in figure 1. The left image shows the complete formatted documentation. The right image is the inbuilt documentation editor in Dymola. The documentation is stored as HTML in the documentation annotation of the model code, and HTML can also be viewed in the Documentation tab.
Figure 2 – Documentation tab in Dymola 2023x. Left: formatted view. Right: info editor.
The documentation formatting can be configured using a Cascading Style Sheet (.css file). You simply need to copy the default example from the Insert directory in the Dymola installation to your library’s Resources folder, add edit it to suit your needs.
The content of a model’s documentation is also shown when a user selects the Info option in a model’s context menu in the package browser or a diagram.
Users Guide
In addition to the information stored in your models, consider creating a library users guide to provide your users with further general guidance, such as:
- Library principles and conventions
- Tutorials
- Release notes
- Contact details
As a users guide only contains information, they usually consist of a package containing class declarations. As we want the Documentation tab to be the default view when we select the users guide, the annotation DocumentationClass=true should be used, as highlighted in Figure 3. Using the green information icon, makes identifying users guide in the package browser easy.
Figure 3 – User guide code content
Model Documentation Outside of Dymola
Your model’s documentation can also be used outside of Dymola by using the HTML export tool. Using the GUI shown in figure 4, you can configure what is exported depending on your needs. The HTML files generated can be used to provide online documentation or to produce printable Word or PDF documents.
Figure 4 – HTML export tool within Dymola
Summing Up
By documenting our models as we create them, we can provide all the information our users need to successfully use our model libraries. We also improve our ability to collaborate with other developers when working together to develop a library, by sharing our knowledge of our models. Well documented models should be far easier to maintain and update when the developers change or memory has faded; increasing their longevity.
For further details on documenting your models in Dymola take a look at section 4.2.8 Documentation of the Dymola 2023x Full User Manual.
Written by: Hannah Hammond-Scott – Modelica Project Leader
Please get in touch if you have any questions or have got a topic in mind that you would like us to write about. You can submit your questions / topics via: Tech Blog Questions / Topic Suggestion.
