Five Ways to Document Your Simulink Model

By Emmanouil Tzorakoleftherakis, MathWorks

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.

Figure 1. A complete vehicle model in Simulink. 

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.

Figure 2. Property Inspector view showing model description.

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.

Figure 3. Model with annotations added. 

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.

Figure 4. Annotated blocks and signals.

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.

Figure 5. Documentation for masked blocks.

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).

Figure 6. Viewmarks detailing specific views of the model. 

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. 

Figure 7. Notes detailing a specific layer in the model 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.

Figure 8. DocBlock with comments added.

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).

Figure 9. Description fields for bus, signal, and parameter objects. 

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).

Figure 10. Using the bus, parameter, and signal object description fields as comments in generated code.

详细了解如何将 Simulink 数据对象的描述插入生成的代码中作为注释以及如何将自定义注释添加到生成的代码中

后续步骤

此时,您可能会问,如果我的项目包含多个 Simulink 模型会怎样?是否有办法扩展到整个项目?ProjectsSimulink Report Generator™Simulink Requirements™等产品为本文讨论的技术提供了自然扩展。

使用 Simulink Report Generator,您可以使用常见格式(如 PDF、Microsoft® Word、Microsoft PowerPoint® 和 HTML)根据模型设计自动生成报告。

Simulink Requirements 允许您创建富文本需求,并将它们链接到设计、代码和测试。您可以检查需求的实现和验证状态,从而评估项目的完整性。

Projects 可以帮助您组织项目,提升团队合作效率和个人生产力。您可以在一个位置管理所有项目文件,查看和标记同事评审工作流的文件,并使用 Subversion® 或 Git™ 等外部源代码控制工具跟踪和共享项目。

Published 2018


View Articles for Related Capabilities