ライブ関数のヘルプの追加

記述するライブ関数についてのヘルプを提供することができます。ヘルプテキストは、help コマンドを使用するとコマンドウィンドウに表示されます。doc コマンドを使用して、ヘルプテキストを別のブラウザーに表示することもできます。

ヘルプテキストの追加

ヘルプテキストを作成するには、ファイルの先頭にある関数定義行 (function キーワードがある行) の直前にテキストを追加します。

たとえば、addme.mlx という名前のライブ関数を作成します。

function c = addme(a,b)

switch nargin
    case 2
        c = a + b;
    case 1
        c = a + a;
    otherwise
        c = 0;
end

関数定義行の直前に行を挿入します。次に、[ライブエディター] タブに移動して [テキスト] ボタンをクリックします。コード行はテキスト行になります。関数について説明するヘルプテキストを追加します。

Add two values
C = ADDME(A) adds A to itself.
C = ADDME(A,B) adds A and B.

"参考" リンクを追加するには、ヘルプテキストの末尾に空のテキスト行を追加してから、See also という語句で始まり、その後に関数名のリストが続く行を追加します。

See also SUM, PLUS

関数が検索パス上か現在のフォルダー内にある場合は、help コマンドを使用すると、これらの各関数名がヘルプテキストへのハイパーリンクとして表示されます。検索パスにない場合、help は、ヘルプテキストに表示される関数名を出力します。リンクが正しく表示されるようにするには、See also テキストが含まれている行の前に空行が必要です。

addme live function with help text above the code, including the function's purpose, supported syntaxes, and related functions

同じ名前をもつ複数のファイルまたは関数がある場合、help コマンドは関数の優先順位で説明されているルールを適用して表示するヘルプテキストを決定します。ただし、ファイルが組み込み関数と同じ名前である場合は、コンテキストメニューの [選択のヘルプ] オプションには組み込み関数のドキュメンテーションが表示されます。

また、ファイルの先頭にコメントを挿入することで、ライブ関数にヘルプを追加することもできます。help コマンドと doc コマンドを使用すると、ファイルの先頭のコメントがヘルプテキストとして表示されます。これは、ファイルの先頭のテキストが表示されるのと同様です。コメントを追加したヘルプの追加の詳細については、プログラムへのヘルプの追加を参照してください。

ヘルプテキストの表示

コマンドウィンドウで「help addme」と入力します。関数 addme のヘルプテキストがコマンドウィンドウに表示されます。ヘルプテキストは関数の名前から始まり、ヘルプテキストの最初の行 (H1 行と呼ばれることが多い) が続きます。次に MATLAB^® は関数の構文を表示します。最後に MATLAB は、残りのすべてのヘルプテキストを表示します。

Command Window showing the help text for the addme live function

「doc addme」と入力して、別のブラウザーに書式設定されたヘルプテキストを表示します。

Separate browser showing the formatted help text for the addme live function

書式設定されたテキストおよび例の追加

doc コマンドを使用したときに表示されるドキュメンテーションを改善するために、ヘルプテキストに書式を設定し、ハイパーリンク、イメージ、数式、およびコード例を追加できます。ヘルプテキストに書式を設定するには、[ライブエディター] タブに移動し、[テキスト] セクションのオプションを選択します。ハイパーリンク、イメージ、数式、およびコード例を挿入するには、[挿入] タブに移動し、利用できるオプションの中から選択します。

たとえば、関数 addme で、"参考" リンクの前にヘッダーと 2 つの MATLAB コード例を追加することで、数式を 2 番目の構文説明に追加し、例のセクションを作成します。

関数 addme で、カーソルを 2 番目の構文説明の終わりに合わせ、[挿入] タブに移動して [式] を選択します。c = a + b という式を入力して Esc キーを押します。
カーソルを "参考" リンクの前の空のテキスト行に合わせ、[ライブエディター] タブに移動して、[見出し 1] テキストスタイルを選択します。「Examples」という単語を入力します。
[挿入] タブに移動して [コード例] 、 [MATLAB] を選択します。表示されたブロックにコード例を入力します。