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

Перевод статьи Five Ways to Document Your Simulink Model.

Автор: Emmanouil Tzorakoleftherakis, MathWorks

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

Существует множество различных способов документирования модели Simulink. Эта статья покажет вам пять вариантов: от высокоуровневых описаний моделей и кратких заметок на холсте до более подробной документации по моделям и блокам. Для иллюстрации каждого метода мы будем использовать модель транспортного средства Simulink, показанную на Рис. 1.

Рисунок 1. Полная модель автомобиля в Simulink.

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

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

Рисунок 2. Вид инспектора свойств, показывающий описание модели.

На вкладке Информация в Инспекторе свойств также выводится история модели, включая изменения, версию и последнюю сохраненную дату.

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

Добавление аннотаций - это еще один способ улучшить читабельность и ясность вашего проекта. Аннотации - это визуальные элементы, которые позволяют быстро добавлять описательные заметки и сноски. Используйте палитру или дважды щелкните на холсте и выберите "Создать аннотацию" (Create Annotation), чтобы создать любую комбинацию текста, изображений, уравнений и ссылок на веб-сайты или функции MATLAB. Вы можете изменить тип и внешний вид вашей аннотации; например, вы можете добавить математические уравнения в LaTeX или MathML.

Вы можете добавить соединительные линии между аннотацией и блоком, поместив курсор на контур аннотации и перетащив соединительную линию к нужному блоку. Вы можете поместить области модели в рамки, чтобы визуально сгруппировать связанные блоки и улучшить читаемость модели. Это делается либо с помощью палитры, либо выделив область вокруг интересующих объектов и выбрав создать область (Create Area) на панели действий. Области могут быть помечены для указания взаимосвязи между блоками.

Рисунок 3 иллюстрирует эти методы аннотирования.

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

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

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

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

Узнайте больше об управлении форматированием, стилем и внешним видом блока.

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

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

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

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

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

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

Видовые метки делают ссылки на части модели: их можно использовать для прямого перехода к определенным частям модели и предоставления подробных сведений или комментариев к определенным видам. Чтобы создать видовую метку, выберите кнопку Viewmark This View на палитре детали модели, которую вы хотите захватить. Нажмите кнопку Viewmarks, чтобы просмотреть и добавить описания или комментарии к вашим видовым меткам (рис.6).

Рисунок 6. Видовые метки, детализирующие конкретные виды модели.

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

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

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

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

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

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

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

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

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

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

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

Подробнее о том, как вставить описание объекта данных Simulink в сгенерированный код в качестве комментария и как добавить пользовательские комментарии в сгенерированный код.

Следующие шаги

На этом этапе вы можете спросить, что произойдет, если мой проект содержит несколько моделей Simulink? Есть ли способ масштабироваться до всего проекта? Такие продукты, как Projects, Simulink Report Generator™ и Simulink Requirements™, обеспечивают естественное расширение технологий, обсуждаемых в этой статье.

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

Simulink Requirements позволяет создавать требования к форматированному тексту и связывать их с дизайном, кодом и тестированием. Вы можете проверить состояние реализации и проверки требований, чтобы оценить целостность проекта.

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