Five Ways to Document Your Simulink Model

Have you ever opened one of your older Simulink^® models or a model developed by a colleague and found that you couldn’t figure out how it worked? Proper documentation can be very helpful in this situation. It can also boost your productivity and facilitate cross-team collaboration.

There are many different ways to document a Simulink model. This article will guide you through five options, from high-level model descriptions and quick canvas notes to more detailed model and block documentation. To illustrate each method, we’ll use the Simulink vehicle model shown in Figure 1.

Specifying and Displaying Model Information

The first action you may want to take is to provide a high-level description. You can view and edit the Description property of the model in the Property Inspector view (Figure 2), or by right-clicking on the canvas and selecting Model Properties. To view the model description, enter help followed by the model name at the MATLAB^® command prompt.

The Info tab in the Property Inspector also summarizes the model history, including modifications, version, and last saved date.

Annotating the Model

Adding annotations is another way to improve the readability and clarity of your design. Annotations are visual elements that let you quickly add descriptive notes and callouts. Use the palette or double-click on the canvas and select Create Annotation to create any combination of text, images, equations, and links to websites or to MATLAB^® functions. You can modify the type and appearance of your annotation; for example, you can add mathematical equations in LaTeX or MathML.

You can add connector lines between an annotation and a block by placing the cursor over the annotation outline and dragging the connector line to the desired block. You can box areas of your model to visually group related blocks and improve model readability, either by using the palette or by dragging a box around the area of interest and selecting Create Area from the action bar. Areas can be labeled to indicate the relationship between blocks.

Figure 3 illustrates these annotation techniques.

Documenting Blocks and Signals

As your design progresses, you’ll probably find yourself working with hundreds or even thousands of blocks and signals, making the model even more challenging to read.

You can immediately improve design clarity by naming signals and blocks (Figure 4). To enter or edit a signal name, right-click the signal and select Properties or simply double-click the signal. To name a block, click on the default name right below the block.

Learn more about controlling the formatting, style and appearance of a block.

Enter descriptions for a block or signal, using the respective field in the block or signal properties. You can then display the description and other block properties below the block icon or while hovering over the block. Annotated blocks and signals are shown in Figure 4. You can also include the block description as a comment in C/C++ code generated from your model.

If you use masks to define custom interfaces in your blocks, you can still provide a description in the Documentation pane of the Mask Editor (Figure 5). The Help field in the same pane lets you enter information that you would like to appear when the masked block user clicks the Help button on the mask dialog box.

Adding Notes to Model Layers

As models become larger, more layers are added to the hierarchy, making it difficult to capture the full picture. You can annotate individual layers of a model using viewmarks, notes, and the DocBlock.

Viewmarks bookmark parts of a model— you can use them to navigate directly to specific parts of your model and to provide details or comments on specific views. To create a viewmark, select the Viewmark This View button from the palette on the model part that you want to capture. Click the Viewmarks button to view and add descriptions or comments to your viewmarks (Figure 6).

To add notes to any layer in your model hierarchy, you first need to create a notes file. Notes can include images and links, as well as URLs (Figure 7). If the model already has notes associated with it, the Notes pane displays the content for the current layer as you navigate the hierarchy. 

The DocBlock gives you another way to add notes. Double-clicking an instance of the block creates a temporary file containing the text associated with this block and opens the file in an editor (Figure 8). Note that you can use the comment text in a DocBlock as a global comment that appears in code generated from your model.

Documenting Buses, Signals, and Parameters

A Simulink model often relies on variables and data stored outside the model—for example, bus, signal, and parameter objects are often stored in the base workspace. You can detail the role and functionality of an object using its Description property. This can be done either programmatically:

>> myParam = Simulink.Parameter; myParam.Description = 'This is the parameter description';

or from the corresponding dialog box, accessible from the Model Explorer or by double-clicking the object (Figure 9).

If you are using Embedded Coder^® to generate code from your model, you can add the bus, signal, and parameter object descriptions as comments for the variable declarations in the generated code (Figure 10).

Learn more about inserting descriptions of Simulink data objects into generated code as comments and adding custom comments to generated code.

Next Steps

At this point, you may be wondering, what if my project includes multiple Simulink models? Are there ways to scale up to an entire project? Projects and products like Simulink Report Generator™ and Requirements Toolbox™ provide natural extensions to the techniques discussed in this article.

With Simulink Report Generator you can design and automatically generate reports from your models in common formats such as PDF, Microsoft^® Word^®, Microsoft PowerPoint^®, and HTML.

Requirements Toolbox lets you create rich text requirements and link them to designs, code, and tests. You can check the implementation and verification status of your requirements, enabling you to assess project completeness.

Projects can help you organize your projects and promote efficient team work as well as individual productivity. You can manage all your project files in one place, view and label files for peer review workflows, and track and share your projects with external source control tools such as Subversion^® or Git™.