为 Simulink 模型添加注解的五种方式
作者 Emmanouil Tzorakoleftherakis, MathWorks
您是否有过这样的经历，当打开旧版本的 Simulink®模型或某个同事开发的模型时完全搞不清如何使用？在这种情况下，添加恰当的注解会非常有帮助。这样还会提高生产效率，促进跨团队协作。
可以采用多种不同方式为 Simulink 模型添加注解。本文为您介绍五种方法，包括高级模型描述、快速画布备注以及更加详细的模型和模块文档注解等。我们将使用图1所示的 Simulink 汽车模型来演示各种方法。
图 1Simulink 中的完整汽车模型。
指定和显示模型信息
第一步是创建高级描述。您可以在 Property Inspector（属性查看）中或者右键单击画布并选择Model Properties（模型属性）查看和编辑模型的 Description （描述）属性。若要查看模型描述，请在MATLAB® 命令提示中（图2，左上角）输入help，然后再输入模型名称。
图 2显示模型描述的Property Inspector（属性查看）视图。
Property Inspector（属性查看）中的Info（信息）选项卡还会概要显示模型历史信息，包括变动、版本和上次保存的日期。
详细了解如何使用Model History（模型历史信息）字段创建和保存模型变更记录。
为模型添加注释
添加注释是另一种提升设计可读性和清晰度的方式。注释是快速添加描述性备注和标注的视觉元素。使用选项板或者双击画布并选择 Create Annotation（创建注释），可创建文本、图像、方程、网站链接或 MATLAB 函数链接的组合。您可以修改注释的类型和外观；例如，您可以在 LaTeX 或 MathML 中添加数学方程式。
通过将光标放在注释轮廓上并将连接线拖动到目标模块上，可以在注释和模块之间添加连接线。通过使用选项板或在感兴趣的区域周围拖动一个框并从操作栏中选择 Create Area(创建区域)，可以将模型中的各区域框起来，以直观地对相关模块进行分组并提高模型的可读性。可以标记区域以指示模块之间的关系。
图 3 说明了这些注释技巧。
图 3添加了注释的模型。
为模块和信号加注解
随着设计的进展，您可能会发现自己要处理数百甚至数千个模块和信号，这使得模型更加不易阅读。
通过命名信号和模块，可以立即提高设计的清晰度（图 4）。右键单击该信号并选择 Properties（属性），或者只需双击该信号即可输入或编辑信号名称。单击模块正下方的默认名称即可命名该模块。
详细了解如何控制模块的格式、样式和外观。
图 4添加了注释的模块和信号。
使用模块或信号属性中的相应字段输入模块或信号的描述。随后，您可以在模块图标下方或在模块上方悬停时显示描述和其他模块属性。带注释的模块和信号如图5所示。您还可以将模块描述作为注释包含在从模型生成的 C/C++代码中。
如果使用封装技术创建模块的自定义接口，用户仍然可以在 Mask Editor 的Documentation（文档） 窗格中提供描述（图6）。同一窗格中的Help（帮助）字段可以让您输入所需信息，该信息会在用户单击封装模块对话框的Help（帮助）按钮时显示。
图 5屏蔽模块的说明文档。
向模型层添加备注
随着模型越来越大，层次结构中也添加了越来越多的层，这使得研发人员很难掌握整体情况。可以使用视图标签、备注和 DocBlock 对模型的各个层进行注解。
对部分模型打视图标签书签，您可以使用它们直接导航到模型的特定部分，并提供特定视图的详细信息或注释。要创建视图标签，可从想要捕获的模型部分的选项板中选择Viewmark This View（标注此视图）按钮。单击Viewmarks（视图标签）按钮，查看并向您的视图标签添加描述或注释（图 6）。
图 6 详细说明模型特定视图的Viewmarks（视图标签）。
要将备注添加到模型层次结构中的任何层，首先需要创建一个备注文件。备注可以包括图像和链接，以及URL（图 7）。如果模型已经有了与之关联的备注，则在层次结构中导航时，Notes（备注）窗格将显示当前层的内容。
图 7详细说明模型层次结构中特定层的Notes（备注）。
DocBlock 为您提供了另一种添加备注的方法。双击模块的某个实例，可创建一个包含该模块关联文本的临时文件，并在编辑器中打开该文件（图 8）。请注意，可以将 DocBlock 中的注释文本用作全局注释（该注释显示在从模型生成的代码中）。
图 8添加了注释的 DocBlock。
为总线、信号和参数添加注解
Simulink 模型通常依赖于存储在模型外部的变量和数据。例如，总线、信号和参数对象一般存储在基本工作空间中。您可以使用对象的Description属性详细说明对象的作用和功能。该功能可以通过编程实现：
>> myParam = Simulink.Parameter; myParam.Description = 'This is the parameter description';
也可以从相应的对话框中通过 Model Explorer（模型资源管理器）访问或双击对象来实现（图 9）。
图 9总线、信号和参数对象的 Description(描述)字段。
如果使用 Embedded Coder® 从模型生成代码，则可以将总线、信号和参数对象描述添加为生成代码中变量声明的注释（图 10）。
图 10将总线、参数和信号对象描述字段用作生成代码中的注释。
详细了解如何将 Simulink 数据对象的描述插入生成的代码中作为注释以及如何将自定义注释添加到生成的代码中。
后续步骤
此时，您可能会问，如果我的项目包含多个 Simulink 模型会怎样？是否有办法扩展到整个项目？Projects 和 Simulink Report Generator™ 及 Requirements Toolbox™等产品为本文讨论的技术提供了自然扩展。
使用 Simulink Report Generator，您可以使用常见格式（如 PDF、Microsoft® Word、Microsoft PowerPoint® 和 HTML）根据模型设计自动生成报告。
Requirements Toolbox 允许您创建富文本需求，并将它们链接到设计、代码和测试。您可以检查需求的实现和验证状态，从而评估项目的完整性。
Projects 可以帮助您组织项目，提升团队合作效率和个人生产力。您可以在一个位置管理所有项目文件，查看和标记同事评审工作流的文件，并使用 Subversion® 或 Git™ 等外部源代码控制工具跟踪和共享项目。
2018年发布
