Пять способов документировать вашу Simulink модель

Думаю, все сталкивались с ситуацией, когда вы сделали модель и отложили ее на долгое время, и потом, вернувшись к ней, долго не можете понять, что это вообще за модель и как все в ней работает. 

В данном случае может помочь лишь одно - правильно составленная документация, которая может не только увеличить вашу продуктивность в будущем, но и улучшить командную работу, ведь с ней коллега или вы быстро сможете узнать, что из себя данная модель представляет.

И сегодня мы с вами разберем пять способов правильного составления документации для любой Simulink-модели.

Существует множество способов документирования модели, но в данной статье я опишу лишь пять из них: от высокоуровневых описаний модели и быстрых заметок до более подробных документаций по моделям и блокам.

Чтобы проиллюстрировать каждый способ, мы будем использовать проект беспилотной машинки Racecar/J, про который мы рассказывали в предыдущих наших статьях.
А именно - модель локализации Монте-Карло, которую вы можете увидеть на рисунке 1:

Рисунок 1. Модель Racecar/J: локализация Монте-Карло

 

Уточнение и отображение информации о модели

Первое действие, которое вы можете предпринять, - это предоставить высокоуровневое описание. Вы можете просмотреть и отредактировать свойство Description модели в диалоговом окне Property Inspector (рис. 2) или щелкнув правой кнопкой мыши на холсте и выбрав Свойства модели. Чтобы просмотреть описание модели, введите help, за которым следует имя модели в командной строке MATLAB®.

 

Рисунок 2. Вид диалогового окна Property Inspector, отображающего описание модели

На вкладке Info диалогового окна Property Inspector также отображена информация об истории модели, включая модификации, версию и дату последнего сохранения.

Аннотирование модели

Добавление аннотаций - еще один способ улучшить читаемость и ясность вашей модели. Аннотации - это визуальные элементы, которые позволяют быстро добавлять описательные заметки и выноски. Используйте палитру или дважды щелкните на холсте и выберите Create Annotation, чтобы создать любую комбинацию текста, изображений, уравнений и ссылок на веб-сайты или на функции MATLAB®.

Вы можете изменить тип и внешний вид аннотации; например, вы можете добавлять математические уравнения в форматах LaTeX или MathML. Вы можете добавить соединительные линии между аннотацией и блоком, поместив курсор на контур аннотации и перетащив соединительную линию на нужный блок.

Вы можете создать рамку для областей модели (Group Using Area на вкладке Modeling -> Component), чтобы визуально сгруппировать связанные блоки и улучшить читаемость модели, используя палитру или перетаскивая рамку вокруг интересующей области и выбирая «Создать область» на панели действий. Области могут быть помечены, чтобы указать взаимосвязь между блоками.

На рисунке 3 отображены различные иллюстрации вышеприведенных аннотаций:

Рисунок 3. Модель с добавленными аннотациями

Документирование блоков и сигналов

По мере развития вашей модели вы, вероятно, обнаружите, что работаете с сотнями или даже тысячами блоков и сигналов, что сделает модель еще более сложной для чтения.

Вы можете сразу улучшить ясность вашего дизайна модели, назвав сигналы и блоки (рисунок 4). Чтобы ввести или отредактировать имя сигнала, щелкните на сигнал правой кнопкой мыши и выберите «Properties» или просто дважды щелкните на сигнал. Чтобы присвоить блоку имя, щелкните на имя по умолчанию под блоком.

Более подробную информацию о форматировании, стиле и внешнем виде блоков вы можете найти здесь.

Рисунок 4. Аннотированные блоки и сигналы

Введите описание блока или сигнала, используя соответствующее поле в свойствах блока или сигнала. Также вы можете отобразить описание и другие свойства блока под значком блока или при наведении курсора на блок.

Аннотированные блоки и сигналы показаны на рисунке 4. Вы также можете включить описание блока в качестве комментария в C/C++ коде, сгенерированного из вашей модели.

Если вы используете маски для определения пользовательских интерфейсов в своих блоках, вы все равно можете предоставить описание в панели документации редактора масок (рисунок 5). В поле «Documentation» на той же панели можно ввести информацию, которая должна отображаться, когда пользователь замаскированного блока нажимает кнопку «Documentation» в диалоговом окне маски.

Рисунок 5. Документация для блоков с маской

Добавление заметок на слои модели

По мере того, как модели становятся больше, к иерархии добавляется больше слоев, что затрудняет получение полной картины. Вы можете аннотировать отдельные слои модели с помощью меток просмотра, заметок и DocBlock. Метки просмотра создают закладки для частей модели - вы можете использовать их для перехода непосредственно к определенным частям вашей модели, а также для предоставления сведений или комментариев к определенным видам.

Чтобы создать метку просмотра, нажмите кнопку «Отметить этот вид» на палитре той части модели, которую вы хотите зафиксировать. Нажмите кнопку Метки просмотра, чтобы просмотреть и добавить описание или комментарии к вашим меткам просмотра (рисунок 6).

Рисунок 6. Метки просмотра, отображающие отдельные виды модели

Чтобы добавить примечания к любому слою в иерархии вашей модели, вам сначала нужно создать файл заметок. Примечания могут включать изображения и ссылки, а также URL-адреса (рисунок 7). Если с моделью уже связаны примечания, на панели «Примечания» отображается содержимое текущего слоя по мере перемещения по иерархии.

Рисунок 7. Заметки, описывающие определенный слой в иерархии модели

DocBlock дает вам еще один способ добавления заметок. Двойной щелчок по экземпляру блока создает временный файл, содержащий текст, связанный с этим блоком, и открывает файл в редакторе (рисунок 8).

Обратите внимание, что вы можете использовать текст комментария в DocBlock как глобальный комментарий, который появляется в коде, созданном на основе вашей модели.

Рисунок 8. DocBlock с добавленным комментарием

Документация шин, сигналов и параметров объекта

Модель Simulink часто полагается на переменные и данные, хранящиеся вне модели - например, объекты шины, сигналов и параметров часто хранятся в базовом рабочем пространстве. Вы можете подробно описать роль и функциональные возможности объекта, используя его свойство Description. Это можно сделать либо программно:

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

или из соответствующего диалогового окна, доступного из Model Exporer или по двойному щелчку на объекте (рисунок 9).

Рисунок 9. Поля описания для шин, сигналов и параметров объектов

Если вы используете Embedded Coder® для генерации кода из вашей модели, вы можете добавить описания объектов шины, сигналов и параметров в качестве комментариев к объявлениям переменных в сгенерированном коде (рисунок 10).

Рисунок 10. Использование описаний шин, сигналов и параметров объекта как комментариев в сгенерированном коде

Также вы можете узнать больше о вставке описаний объектов данных Simulink в сгенерированный код в качестве комментариев и добавлении пользовательских комментариев к сгенерированному коду.

Заключение

На этом этапе вам может быть интересно:а что, если мой проект включает несколько моделей Simulink? Есть ли способы масштабирования для всего проекта?

Проекты и продукты, как Simulink Report Generator ™ и Simulink Requirements ™, обеспечивают естественное расширение методов, обсуждаемых в этой статье.

С помощью Simulink Report Generator вы можете проектировать и автоматически генерировать отчеты из ваших моделей в распространенных форматах, таких как PDF, Microsoft® Word®, Microsoft PowerPoint® и HTML.

Simulink Requirements позволяет создавать требования к форматированному тексту и связывать их с проектами, кодом и тестами. Вы можете проверить статус выполнения и проверки ваших требований, что позволит вам оценить завершенность проекта. Проекты могут помочь вам организовать ваши проекты и способствовать эффективной командной работе, а также индивидуальной производительности. Вы можете управлять всеми файлами своего проекта в одном месте, просматривать и маркировать файлы для рабочих процессов экспертной оценки, а также отслеживать и делиться своими проектами с помощью внешних инструментов управления версиями, таких как Subversion® или Git ™.

На этом наша статья заканчивается. Всем спасибо за просмотр и удачи!