matlab-write-help

使用する場面

• 新しい MATLAB 関数、クラス、またはスクリプトのヘルプテキストを作成する場合
• 不完全または規則に準拠していない既存のヘルプテキストを書き直す、または改善する場合
• ヘルプテキストが規格に準拠しているか確認する場合
• classdef ファイル内のメソッドにヘルプを追加する場合
• クラスのプロパティコメントを生成する場合

使用しない場面

• 一般的なドキュメントや README ファイルを作成する場合（ヘルプコメントではないもの）
• コードを生成する場合 — このスキルで生成するのはヘルプテキストのみです
• MATLAB 以外の言語を扱う場合
• MATLAB Live Script のマークアップを作成する場合（代わりにプレーンテキストのライブコード用ガイドラインを使用してください）

タスク

$file を M ファイルのパスとして解決し、そのファイル用に完全で規格に準拠した MATLAB ヘルプテキストを生成します。ファイルにヘルプテキストがすでにある場合は、以下の規格に適合するように改善します。ファイルを変更する前に、提案するヘルプテキストをユーザーに提示して確認してもらいます。

MATLAB ヘルプテキストの規格

以下のルールはすべて必須です。いずれかに違反すると、ヘルプテキストは規格に準拠しません。

一般規則

• 関数／クラスの場合、ヘルプは 2 行目（function または classdef 行の後）から始めます

• スクリプトまたは組み込みのサイドカーファイルの場合、ヘルプは 1 行目から始めます

• ヘルプコメントのインデントは、本文コードのインデントと一致させます。 ヘルプブロックの後にある最初のコメント以外の内容を確認して、 インデントレベルを判断します。

  • classdef ファイルの場合：本文は properties／methods ブロックで、 常に 4 つのスペース分インデントされます → クラスのヘルプも 4 つのスペース分インデントします
  • function ファイルの場合：最初の実行文を確認します。 1 列目から始まる場合はヘルプも 1 列目から、4 つのスペース分インデントされている場合はヘルプも 4 つのスペース分インデントします。 4 つのスペース分インデントする例：

    function result = myFunc(x)
        %myFunc - X の処理を行います
        %   RESULT = myFunc(X) は X を使って何かを行います。
        result = x + 1;
    end
    

  • classdef 内のインラインメソッドの場合：本文が 12 つのスペース分インデントされている場合、ヘルプも 12 つのスペース分インデントします トップレベル関数では、どちらのスタイルも有効です。ファイルですでに使われているスタイルに合わせてください。ファイルのインデントスタイルを変更してはいけません

• コメント行は % 以降の文字数が 75 文字を超えてはいけません（% 自体を含むコメント内容が 75 文字以内）。 % がインデントされている場合、行全体の幅はインデント + 75 文字です。 構文行は対象外です（下記参照）。

  最大列 = インデント + 75（例：インデント 12 の場合、最大列は 87）。 1 列目ではなく、% から数えます。

• タブは使わず、スペースのみを使用します

• 行末に空白を入れません

• ブロックコメント（%{ %}）は使用せず、% 行コメントのみを使用します

• ドキュメントやウェブページへの固定リンクを記述しません

• 'href="matlab:' の評価リンクは使用しません

セクションの順序

1. H1 行
2. リリース互換性（該当する場合）
3. 構文段落
4. 例（任意）
5. See Also 行
6. 注記（任意）

ヘルプと著作権行の間には、空行（% なし）を入れます。

---

ヘルプ用の大文字・小文字表記

関数名やクラス名がヘルプテキスト（H1 行、構文段落、本文中の参照、See Also 行）に現れる場合は、通常の単語と区別するため、ヘルプ用の大文字・小文字表記を使用します。help コマンドでは、ヘルプ用の表記をした名前が太字またはハイパーリンクとして表示されます。

ルール：

• 名前が小文字の英字 [a-z] のみで構成される場合は、大文字にします （例：sort → SORT、magic → MAGIC）
• 大文字で始まり、残りがすべて小文字の名前も大文字にします （例：Table → TABLE、Handle → HANDLE）
• それ以外の名前（大文字・小文字の混在、数字、またはアンダースコアを含むもの）は、元の表記をそのまま維持します。大文字にしてはいけません （例：readTable → readTable、XMLReader → XMLReader、 image_resize → image_resize、pdist2 → pdist2）

---

H1 行

%FUNCNAME - Brief description without a period

• % の直後に、ヘルプ用の表記にした関数名を置いて始めます（% の後にスペースを入れません）
• 名前空間名やクラス名を含めてはいけません
• 名前と説明は -（スペース、ハイフン、スペース）で区切ります
• ピリオドで終えてはいけません
• 説明は、関数の目的を簡潔にまとめます

構文の段落

%FUNC - Brief description without a period
%   B = FUNC(A,OPTION) does the thing with A using OPTION.
%
%   B = FUNC(A,Name=VALUE) also specifies a name-value argument.

注：H1 と最初の構文の段落の間に、空の % 行を入れないでください。

• 構文ごとに段落を 1 つ作成します

• 各段落は、説明する構文の後に小文字の動詞を続けます。構文が文の主語となるようにします （例：% B = FUNC(A) does...。% B = FUNC(A) Returns... ではありません）

• 関数名にはヘルプの大文字・小文字表記を使用します

• % の後に 3 つのスペースを入れて、すべての行をインデントします（つまり % ）

• 最初の構文の段落の前に、空の % 行を入れません

• 構文の段落ごとに、空の % 行を挟みます

• 構文内の入力の順序：必須 → オプション → 名前と値

• 最初の構文の段落には、必須入力のみをすべて記述します

• 最初の構文の段落には主出力のみを記述します。追加の出力は、後続の構文の段落で 1 つずつ導入します。出力を 1 つから一度にすべての出力へ増やしてはいけません。新しい出力ごとに段落を作成します。これは入力の段階的な追加に対応しています。シンプルなものから始め、複雑さを 1 つずつ加えます。例：

  出力が 2 つの場合 — 追加の段落は 1 つ：

  %   IDX = FINDNEAREST(POINTS,TARGET) finds the nearest point.
  %
  %   [IDX,DIST] = FINDNEAREST(...) also returns the distances.
  

  出力が 3 つの場合 — 追加の段落は 2 つ（1 つではありません）：

  %   SEGMENTS = segmentSignal(DATA,THRESHOLD) segments the signal.
  %
  %   [SEGMENTS,BOUNDARIES] = segmentSignal(...) also returns the
  %   boundary indices where segments split.
  %
  %   [SEGMENTS,BOUNDARIES,LABELS] = segmentSignal(...) also returns
  %   string labels for each segment.
  

• オプションがそれ以前のすべての構文に適用される場合、以前に説明した引数を省略するには ... を使用します

• 構文が 75 文字を超える場合、構文自体は折り返しの対象外とし、1 行に収めます。後続の説明文は通常どおり、次の行から折り返します。長い構文を短くするには：

  • 以前の構文で出力を説明している場合、LHS を [...] で省略します（例：[...] = func(...,Name=VAL)）
  • 以前に説明した入力は、RHS を ... で省略します
  • 2 種類の省略を組み合わせることもできます

構文での変数名

• 入力と出力には、ヘルプの大文字・小文字表記を使用します — すべて小文字の名前は大文字にし、大文字、数字、またはアンダースコアを 1 つでも含む名前は、元の表記をそのまま維持します 例：data → DATA、method → METHOD、result → RESULT、 depth → DEPTH、obj → OBJ、tf → TF ただし、filePath → filePath、queryPoints → queryPoints、 startSample → startSample、maxMemory → maxMemory、 otherBuffer → otherBuffer （これらには大文字が含まれるため、元の表記を維持します）
• 説明文で他の関数に言及する場合は、ヘルプの大文字・小文字表記を使用します。同じフォルダー内の関数には、完全修飾名を使用しません
• 汎用の論理出力には TF を使用します
• 汎用データには、1 文字の大文字（A、B、X）を使用します
• コマンド形式の引数はすべて大文字にします

フラグ（オプション文字列）入力

%   B = SORT(A,DIRECTION) also specifies the sort direction. DIRECTION
%   must be:
%       "ascend"  - (default) Sorts in ascending order.
%       "descend" - Sorts in descending order.

• 構文内のフラグ名は大文字にします
• 許可される値は二重引用符で囲んで列挙します
• % の後に 7 つのスペースを入れて、値をインデントします（つまり % ）
• 値と説明の間は -（スペース、ハイフン、スペース）で区切ります
• 短い値にはスペースを足して、ハイフンが縦に揃うようにします
• デフォルト値は、説明の先頭に (default) と記します
• デフォルト値を最初に記載します

名前と値の引数

%   B = FUNC(A,...,Name=VALUE) also specifies the thing.

• Name=VALUE の形式で記述し、値は大文字にします
• 名前と値の引数に許可される値がある場合は、上記のフラグと同じルールで列挙します

---

例のセクション

%   Example: Brief label describing the example
%       x = func(input1,input2);
%       disp(x)

• 分かりにくい構文の使い方を説明するのに役立つ場合にのみ、例を含めます
• 前に空の % 行を入れます
• 見出し：% Example:（または % Example: label）
• % の後に 7 つのスペースを入れて、コードをインデントします（つまり % ）
• 制御フロー（for、if、while）は使用しません
• Command Window にコピーして実行できる必要があります
• 例ごとのコードは 10 行以内にします
• 複数の例を記載する場合は、空の % 行で区切ります
• 例に番号を付けてはいけません。見出し行に説明ラベルを記載します
• 行の間に文章を挟まず、コード内の % コメント を使って注釈を加えます

---

See Also 行

%
%   See also readtable, griddedInterpolant, pdist2

• 空の % 行が前に付く
• % See also で始まる（3 文字分のインデント）
• 名前は MATLAB パス上に表示されるとおりの元の大文字小文字を正しく保った綴りを使用します（例: readtable、griddedInterpolant、pdist2）— See Also の名前にヘルプの大文字小文字ルールを適用しないでください
• 解決される最短の名前を使用します。パッケージのない MATLAB パス上の関数は、パッケージ名なしの名前を使用できます。他のパッケージ内の関数は、必ず完全修飾する必要があります（例: pkg.subpkg.funcName）。同じフォルダー（同じパッケージレベル）内の関数は、パッケージ名なしの名前を使用します — これらは互いに相対的に解決されます
• プライベートメソッドやプライベート関数を参照しないでください — これらは完全修飾なしでは help から到達できず、完全修飾したとしてもクラス内からしか到達できません。@class フォルダーでは、クラスコンストラクター以外のファイルはすべてメソッドです。参照する前にその Access を確認してください
• @class フォルダー内のメソッドには、クラス自体とそのクラスの関連するパブリックメソッドまたはプロパティを参照する See Also 行を付ける SHOULD があります。その際は非修飾名を使用します（例: ClassName、methodName、propertyName）。他のプライベートメソッドを参照しないでください
• カンマとスペースで区切る
• ピリオドで終端しない
• 項目数は 2 から 7
• 説明を含めないでください — 名前のみです
• 行が 75 文字を超える場合は、カンマの区切りで折り返します:

  %   See also readtable, readtimetable,
  %   griddedInterpolant, scatteredInterpolant
  

---

Note セクション

%
%   Note: FUNC is in the Signal Processing Toolbox

• 空の % 行が前に付く
• % Note: で始まる
• 関数は H1 の大文字小文字ルールを使用します
• 製品は正式名称を使用します
• ピリオドで終端しない

---

Copyright 行

Copyright 行とは、具体的には次に一致するコメントです:

%   Copyright YYYY

ここで、行は % に続いてスペース、次に Copyright という単語全体、次に 4 桁の年または年の範囲（例: 2024 または 2020-2025）で始まります。関数名や説明の一部として "copyright" という単語を含むだけの他のコメントは、Copyright 行ではありません。

• Copyright はヘルプテキストの一部ではありません
• ファイルに Copyright コメントが存在する場合は、ヘルプブロックの後に、空行（% ではなく、単なる改行）で区切って配置されていることを確認してください
• この空行がヘルプブロックを終端します。MATLAB の help コマンドは最初の非コメント行で読み取りを停止します
• Copyright 行は、その上にあるヘルプコメントと一致するようにインデントする必要があります
• Copyright を追加、削除、変更しないでください — 必要な場合のみ移動してください

---

クラスのヘルプ

classdef ファイルの場合:

• メインのクラスヘルプは構築について説明します（コンストラクター用のヘルプを別途書かないでください）
• 構文の段落は、同じ必須/任意のルールに従います: 最初の構文は必須引数のみを示し、各任意引数にはそれぞれ独自の段落を付けます。MyClass(data, opts)（data が必須）の例:

  %   OBJ = MyClass(DATA) creates an object from DATA.
  %
  %   OBJ = MyClass(DATA, sampleRate) also specifies the sample rate.
  

• 構文の段落の後に、クラスの詳細リストを含めます:

%   CLASSNAME functions:
%       method1 - Brief description
%       method2 - Brief description
%
%   CLASSNAME properties:
%       Prop1   - Brief description
%       Prop2   - Brief description

• 見出しは必ず CLASSNAME functions: とします — methods ではなく functions という単語を使用してください（MATLAB 自身の help 出力と一致します）。CLASSNAME methods: とは決して書かないでください
• すべてのパブリックメソッドとプロパティをリストします
• ダッシュが揃うように名前をパディングします
• classdef ファイル自身の See Also では、そのクラス自身のメソッドやプロパティをリストしないでください（それらは上記のリストにすでに含まれています）
• メソッドファイル（@class フォルダー）では、クラス自体と他のパブリックメソッドまたはプロパティを参照してください — 非修飾名を使用します（例: ClassName、methodName、propertyName）

プロパティのヘルプ

classdef ファイルのヘルプを生成するときは、常にすべてのパブリックプロパティにコメントがあることを確認してください。 これは任意ではなく、ユーザーに尋ねられるべきものでもありません — 標準的な classdef ヘルプワークフローの一部です。コメントのないパブリックプロパティがある場合は、コメントを追加してください。

すべてのパブリックプロパティには、少なくとも後置コメントを付ける必要があります:

後置（短く、H1 のみ）:

    PropName  % Brief description

前置（より長い説明の場合）:

    %PROPNAME - Brief description
    %   Additional detail about the property.
    PropName

プロパティにすでに後置コメントがある場合は、そのままにしてください。不足しているものだけを追加します。クラスレベルのプロパティリストを重複させないでください — リストは要約であり、プロパティレベルのコメントはインラインドキュメントです。

メソッドのヘルプ

@class フォルダー内の個別ファイルではなく、classdef ファイル内にローカル定義されたメソッドには、アクセスレベルに応じて次のルールが適用されます。

パブリックメソッドには、完全な関数ヘルプを記述します。

• H1 行
• すべての入力と出力を説明する構文の段落
• H1 と構文の段落の間に空の % 行を入れない
• 説明文は、% から数えて 75 文字幅いっぱいまで埋めます。短い行を折り返さないでください
• 構文自体（例：% OUT = func(A,B,C)）は 75 文字制限の対象外です。構文は複数行に分割しないでください。構文が 75 文字を超える場合は、説明を次の行に記述します

        function result = myMethod(obj, x)
            %myMethod - Brief description
            %   RESULT = myMethod(OBJ,X) does something with X.
            result = x + 1;
        end

protected メソッドと private メソッドには、H1 のみを記述します。

        function result = helperMethod(obj)
            %helperMethod - Brief description
            result = obj.data;
        end

アクセスレベルに関係なく、H1 のみを記述する例外：

• プロパティのゲッター／セッター（get.Prop、set.Prop）
• コンストラクター（クラスレベルのヘルプで構築方法を説明します）
• 単純な何もしないメソッド（本体が空）

オーバーライドされたメソッドとヘルプの継承：

サブクラスがスーパークラスのメソッドをオーバーライドした場合、オーバーライド側にヘルプがなければ、MATLAB はスーパークラスのヘルプを継承します。これを利用して重複を避けます。

• オーバーライド側で同じ処理を行う場合（実装が異なるだけ）は、ヘルプを省略します
• コントラクトが変わる場合（入力／出力が異なる場合）のみ、ヘルプを記述します

スーパークラスのヘルプは、汎用的に記述します。方法ではなく、内容を説明してください。

ローカル定義されたメソッドのヘルプは、メソッド本体に合わせてインデントします（通常、function キーワードが 8 個のスペースで始まる場合は 12 個のスペースです）。

個別ファイル（@class フォルダー内）のメソッドには、それぞれ独立して標準的な関数ヘルプのルールを適用します。ヘルプのインデントは、そのファイル内の本体コードのインデントに合わせます（本体が 1 列目から始まる場合は 1 列目、4 個のスペースでインデントされている場合は 4 個のスペースです）。

---

構文の段落に arguments ブロックを使用する

関数に arguments ブロックがある場合は、ブロックを読み、正しい構文の段落を判断します。ブロックには必要な情報がすべて記載されています。

• 必須の位置引数：既定値を示す = がなく、ドット接頭辞もありません

  inputData (1,:) double;
  

• 省略可能な位置引数：= 既定値 があり、ドット接頭辞はありません

  method (1,1) string = "linear";
  

• 名前と値の引数：グループ名とドットが接頭辞として付いています

  opts.Tolerance (1,1) double = 1e-6;
  

これを使って構文の段落を生成します。

1. 最初の構文：必須の位置引数のみ → 基本の呼び出しを説明します
2. 省略可能な位置引数：それぞれについて、先行するすべての引数を示す（または ... で省略する）段落を記述します
3. 名前と値の引数：追加の構文では Name=VALUE の形式で示します

構文に ARGS のような内部変数名をそのまま記述しないでください。呼び出し側が使用する実際の名前と値のペアに展開します。

---

手順

1. $file を完全なファイルパスに解決します。
   • $file が既存の .m ファイルを指す有効な絶対パスまたは相対パスの場合は、そのパスをそのまま使用します
   • それ以外の場合は、MCP ツールを使用して MATLAB で解決します。

     foundName = which("$file");
     if ~isempty(foundName), disp(foundName), end
     

   • 解決できない場合（MCP が利用できない、MATLAB が実行されていない、または名前が見つからない場合）は、失敗を報告し、有効なパスをユーザーに求めます
2. 解決した M ファイルを読み込みます
3. 関数、classdef、またはスクリプトを特定します
4. 関数に arguments ブロックがある場合は、必須、オプション、名前と値の引数を判断するために読み込みます
5. シグネチャ、入力、出力、動作を分析します
6. 上記のすべてのルールに従ってヘルプテキストの草案を作成します
7. classdef ファイルの場合：すべてのパブリックプロパティにコメントがあるか確認します。コメントのないプロパティには、末尾コメントを追加します。ユーザーからの依頼を待たずに、草案作成の一環として先回りして行います
8. 確認します：% から数えて 75 文字を超える行がないこと、セクションの順序が正しいこと、インデントが正しいこと
9. 草案をユーザーに提示します
10. 承認後、Edit を使用してヘルプテキストをファイルに挿入／置換します

---

Copyright 2026 The MathWorks, Inc.