五种 Simulink 模型文档化方法

您是否曾经打开过自己以前的 Simulink^® 模型或同事开发的模型，却发现无法弄清它的工作原理？在这种情况下，完善的文档会非常有帮助。它还可以提高您的工作效率，促进跨团队协作。

记录 Simulink 模型的方法有很多种。本文将为您介绍五种方式，从高层次的模型描述和画布快速备注，到更详细的模型和模块文档。为了说明每种方法，我们将使用图 1 所示的 Simulink 车辆模型。

指定和显示模型信息

您可能首先需要提供一个高层次的描述。您可以在属性检查器视图中查看和编辑模型的“描述”属性（图 2），也可以右键点击画布并选择模型属性来查看和编辑。要查看模型描述，请在 MATLAB^® 命令提示符下输入 help，后跟模型名称。

属性检查器中的“信息”选项卡还汇总了模型历史记录，包括修改、版本和上次保存日期。

为模型添加注释

添加注释是提高设计可读性和清晰度的另一种方法。注释是一种可视化元素，可以让您快速添加描述性说明和标注。使用选项板，或双击画布并选择创建注释，即可创建文本、图像、方程以及网站或 MATLAB^® 函数链接的任意组合。您可以修改注释的类型和外观；例如，您可以使用 LaTeX 或 MathML 添加数学方程。

将光标置于注释轮廓上，并将连接线拖到所需的模块，即可在注释和模块之间添加连接线。您可以框选模型的区域，以便直观地对相关模块进行分组并提高模型的可读性，方法是使用选项板，或者在目标区域周围拖出一个框，然后从操作栏中选择创建区域。可以为区域添加标签，以指示模块之间的关系。

图 3 展示了这些注释方法。

记录模块和信号

随着设计的推进，您可能会发现自己要处理成百上千个模块和信号，这会使模型更加难以阅读。

为信号和模块命名可以立即提高设计的清晰度（图 4）。要输入或编辑信号名称，请右键点击该信号并选择属性，或者直接双击该信号。要为模块命名，请点击模块正下方的默认名称。

详细了解如何控制模块的格式、样式和外观。

使用模块或信号属性中的相应字段，为模块或信号输入描述。然后，您可以在模块图标下方或鼠标悬停在模块上时显示描述和其他模块属性。图 4 显示了带注释的模块和信号。您还可以在从模型生成的 C/C++ 代码中以注释形式包含模块描述。

如果您使用封装为模块定义自定义接口，仍然可以在封装编辑器的“文档”窗格中提供描述（图 5）。在同一窗格的“帮助”字段中，您可以输入希望在封装模块的用户点击封装对话框上的“帮助”按钮时显示的信息。

为模型层添加备注

随着模型变得越来越大，层次结构中的层也越来越多，因此很难掌握全貌。您可以使用视图标记、备注和 DocBlock 为模型的各个层添加注释。

视图标记可以为模型的各个部分添加书签，您可以使用它们直接导航到模型的特定部分，并针对特定视图提供详细信息或评论。要创建视图标记，请在要捕获的模型部分上，从选项板中选择为此视图添加视图标记按钮。点击视图标记按钮，即可查看视图标记并为其添加描述或评论（图 6）。

要为模型层次结构中的任意层添加备注，首先需要创建一个备注文件。备注可以包含图像和链接以及 URL（图 7）。如果模型已有关联的备注，则当您在层次结构中导航时，“备注”窗格会显示当前层的内容。 

DocBlock 为您提供了另一种添加备注的方式。双击该模块的实例会创建一个临时文件，其中包含与该模块关联的文本，并在编辑器中打开该文件（图 8）。请注意，您可以将 DocBlock 中的注释文本用作全局注释，使其出现在从模型生成的代码中。

记录总线、信号和参数

Simulink 模型通常依赖于存储在模型外部的变量和数据，例如，总线、信号和参数对象通常存储在基础工作区中。您可以使用对象的“描述”属性来详细说明其作用和功能。既可以通过编程方式完成：

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

也可以通过相应的对话框完成，该对话框可从模型资源管理器中打开，或通过双击对象打开（图 9）。

如果您使用 Embedded Coder^® 从模型生成代码，可以将总线、信号和参数对象的描述作为生成代码中变量声明的注释（图 10）。

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

后续步骤

此时，您可能想知道：如果我的工程包含多个 Simulink 模型，该怎么办？有没有办法扩展到整个工程？工程以及 Simulink Report Generator™ 和 Requirements Toolbox™ 等产品，是对本文所述方法的自然扩展。

借助 Simulink Report Generator，您可以设计报告，并从模型自动生成 PDF、Microsoft^® Word^®、Microsoft PowerPoint^® 和 HTML 等常见格式的报告。

借助 Requirements Toolbox，您可以创建富文本需求，并将其链接到设计、代码和测试。您可以检查需求的实现和验证状态，从而评估工程的完成度。

工程可以帮助您组织工程，促进高效的团队协作并提高个人工作效率。您可以在一处管理所有工程文件，查看和标记文件以用于同行评审工作流，并使用 Subversion^® 或 Git™ 等外部源代码管理工具跟踪和共享工程。