技術情報

MathWorks インサイト

Simulink モデルを文書化する 5 つの方法


著者:

  • Emmanouil Tzorakoleftherakis, MathWorks

この記事は6分で読めます

以前に作成した Simulink® モデルや同僚が開発したモデルを開いたとき、どのように動作するのか理解できなかった経験はありませんか。このような場合、適切なドキュメンテーションが非常に役立ちます。また、ドキュメンテーションによって生産性が向上し、チーム間のコラボレーションも促進されます。

Simulink モデルを文書化する方法はさまざまです。この記事では、モデルの概要説明やキャンバス上の簡単なメモから、より詳細なモデルやブロックのドキュメンテーションまで、5 つのオプションを紹介します。各手法の説明には、図 1 に示す Simulink の車両モデルを使用します。

図 1. Simulink で構築した車両モデル全体。

図 1. Simulink で構築した車両モデル全体。 

モデル情報の指定と表示

まず、モデルの概要を記述するとよいでしょう。モデルの Description プロパティは、プロパティ インスペクター (図 2) で、またはキャンバスを右クリックして [モデル プロパティ] を選択して、表示および編集できます。モデルの説明を表示するには、MATLAB® コマンド プロンプトで help に続けてモデル名を入力します。

図 2. モデルの説明を表示しているプロパティ インスペクター。

図 2. モデルの説明を表示しているプロパティ インスペクター。

プロパティ インスペクターの [情報] タブには、変更内容、バージョン、最終保存日など、モデルの履歴の概要も表示されます。

モデルへの注釈付け

注釈の追加も、設計の読みやすさとわかりやすさを向上させる方法の 1 つです。注釈は、説明文や吹き出しをすばやく追加できる視覚的な要素です。パレットを使用するか、キャンバスをダブルクリックして [注釈の作成] を選択すると、テキスト、画像、数式、Web サイトや MATLAB® 関数へのリンクを自由に組み合わせて作成できます。注釈の種類や外観は変更できます。たとえば、LaTeX や MathML で数式を追加できます。

注釈とブロックの間に接続線を追加するには、カーソルを注釈のアウトライン上に置き、接続線を目的のブロックまでドラッグします。モデルの領域をボックスで囲むと、関連するブロックを視覚的にグループ化し、モデルの可読性を向上させることができます。パレットを使用するか、対象の領域をボックスで囲むようにドラッグし、アクション バーから [領域の作成] を選択します。各領域には、ブロック間の関係を示すラベルを付けることができます。

図 3 に、これらの注釈付けの手法を示します。

図 3. 注釈を追加したモデル。

図 3. 注釈を追加したモデル。

ブロックと信号の文書化

設計が進むと、数百、あるいは数千ものブロックや信号を扱うことになり、モデルはさらに読みにくくなるでしょう。

信号やブロックに名前を付けると、設計がすぐにわかりやすくなります (図 4)。信号名を入力または編集するには、信号を右クリックして [プロパティ] を選択するか、信号をダブルクリックします。ブロックに名前を付けるには、ブロックのすぐ下にあるデフォルトの名前をクリックします。

ブロックの書式設定、スタイル、外観を制御する方法の詳細をご覧ください。

図 4. 注釈を付けたブロックと信号。

図 4. 注釈を付けたブロックと信号。

ブロックまたは信号のプロパティにあるそれぞれのフィールドを使用して、ブロックまたは信号の説明を入力します。これにより、ブロック アイコンの下に、またはブロックにカーソルを合わせたときに、説明やその他のブロック プロパティを表示できます。注釈を付けたブロックと信号を図 4 に示します。また、モデルから生成した C/C++ コードに、ブロックの説明をコメントとして含めることもできます。

ブロックでマスクを使用してカスタム インターフェイスを定義する場合も、マスク エディターの [ドキュメンテーション] ペインで説明を記述できます (図 5)。同じペインの [ヘルプ] フィールドには、マスクされたブロックのユーザーがマスク ダイアログ ボックスの [ヘルプ] ボタンをクリックしたときに表示する情報を入力できます。

図 5. マスクされたブロックのドキュメンテーション。

図 5. マスクされたブロックのドキュメンテーション。

モデルレイヤーへのメモの追加

モデルが大きくなるにつれて階層のレイヤーが増え、全体像を把握しにくくなります。ビューマーク、メモ、DocBlock を使用すると、モデルの個々のレイヤーに注釈を付けることができます。

ビューマークはモデルの一部をブックマークするもので、これを使用するとモデルの特定の部分に直接移動したり、特定のビューに詳細情報やコメントを追加したりできます。ビューマークを作成するには、記録したいモデルの部分で、パレットの [このビューのビューマークを作成] ボタンを選択します。[ビューマーク] ボタンをクリックすると、ビューマークを表示したり、説明やコメントを追加したりできます (図 6)。

図 6. モデルの特定のビューの詳細を記したビューマーク。

図 6. モデルの特定のビューの詳細を記したビューマーク。

モデル階層内の任意のレイヤーにメモを追加するには、まずメモファイルを作成する必要があります。メモには、画像やリンク、URL を含めることができます (図 7)。モデルにメモが関連付けられている場合は、階層を移動すると、[メモ] ペインに現在のレイヤーの内容が表示されます。 

図 7. モデル階層の特定のレイヤーの詳細を記したメモ。

図 7. モデル階層の特定のレイヤーの詳細を記したメモ。

DocBlock も、メモを追加する方法の 1 つです。このブロックのインスタンスをダブルクリックすると、ブロックに関連付けられたテキストを含む一時ファイルが作成され、エディターでそのファイルが開きます (図 8)。なお、DocBlock のコメント テキストは、グローバル コメントとして使用でき、モデルから生成したコードに表示されます。

図 8. コメントを追加した DocBlock。

図 8. コメントを追加した DocBlock。

バス、信号、パラメーターの文書化

Simulink モデルは、多くの場合、モデルの外部に格納された変数やデータに依存します。たとえば、バス オブジェクト、信号オブジェクト、パラメーター オブジェクトは、ベース ワークスペースに格納されることがよくあります。オブジェクトの役割や機能は、そのオブジェクトの Description プロパティで詳しく記述できます。この記述は、次のようにプログラムで行うことができます。

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

または、対応するダイアログ ボックスで行うこともできます。このダイアログ ボックスは、モデル エクスプローラーから、またはオブジェクトをダブルクリックして開くことができます (図 9)。

図 9. バス オブジェクト、信号オブジェクト、パラメーター オブジェクトの説明フィールド。

図 9. バス オブジェクト、信号オブジェクト、パラメーター オブジェクトの説明フィールド。

Embedded Coder® を使用してモデルからコードを生成する場合は、バス オブジェクト、信号オブジェクト、パラメーター オブジェクトの説明を、生成コード内の変数宣言のコメントとして追加できます (図 10)。

図 10. バス オブジェクト、パラメーター オブジェクト、信号オブジェクトの説明フィールドを生成コードのコメントとして使用。

図 10. バス オブジェクト、パラメーター オブジェクト、信号オブジェクトの説明フィールドを生成コードのコメントとして使用。

Simulink データ オブジェクトの説明をコメントとして生成コードに挿入する方法と、生成コードにカスタム コメントを追加する方法の詳細をご覧ください。

次のステップ

ここで、プロジェクトに複数の Simulink モデルが含まれている場合はどうすればよいのか、と疑問に思われるかもしれません。プロジェクト全体に適用する方法はあるのでしょうか。プロジェクトや、Simulink Report Generator™、Requirements Toolbox™ などの製品を使用すれば、この記事で紹介した手法を自然に拡張できます。

Simulink Report Generator を使用すると、PDF、Microsoft® Word®、Microsoft PowerPoint®、HTML などの一般的な形式で、モデルからレポートを設計し、自動生成できます。

Requirements Toolbox を使用すると、リッチ テキスト形式の要件を作成し、設計、コード、テストにリンクできます。要件の実装状況と検証状況を確認し、プロジェクトの完成度を評価できます。

プロジェクトを使用すると、プロジェクトを整理し、効率的なチームワークを促進するとともに、個人の生産性を高めることができます。すべてのプロジェクト ファイルを 1 か所で管理し、ピア レビュー ワークフローでファイルを表示およびラベル付けし、Subversion® や Git™ などの外部ソース管理ツールでプロジェクトを追跡および共有できます。

公開年 2018


使用製品: Embedded Coder, Stateflow

著者について

Emmanouil Tzorakoleftherakis

Emmanouil Tzorakoleftherakis は、 MathWorks の主任プロダクト マネージャーで、強化学習と制御システムを専門としています。同氏は、ノースウェスタン大学で制御システムとロボティクスに特化した機械工学の修士号と博士号を取得しており、ギリシャのパトラス大学で電気工学とコンピューター工学の学士号を取得しています。

さらに詳しく