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 - Brief description
        %   RESULT = myFunc(X) does something with 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 标题和第一个语法段落之间不能有空白的 % 行。

• 每种语法使用一个段落

• 每个段落以其所描述的语法开头，后接一个小写动词——语法作为句子的主语 （例如，% B = FUNC(A) does...，而不是 % B = FUNC(A) Returns...）

• 函数名称使用帮助文本大小写

• 所有行在 % 后缩进三个空格（即 % ）

• 第一个语法段落前不能有空白的 % 行

• 每个语法段落之间用一个空白的 % 行分隔

• 语法中的输入顺序：必需 → 可选 → 名称-值

• 第一个语法段落仅描述所有必需输入

• 每个可选输入各自使用一个语法段落

• 第一个语法段落仅显示主要输出。其他输出在后续语法段落中逐一引入——不能一次从一个输出直接跳到所有输出。每个新增输出都使用自己的段落。这与输入的分层方式一致——从简单开始，每次增加一项复杂内容。示例：

  两个输出——增加一个段落：

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

  三个输出——增加两个段落（而非一个）：

  %   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 个字符，则语法本身无需换行——保持在一行内。后续的描述文本仍正常换行，并从下一行开始。要缩短较长的语法：

  • 如果输出已在较早的语法中描述过，则使用 [...] 缩写 LHS（例如，[...] = func(...,Name=VAL)）
  • 使用 ... 缩写之前描述过的输入，即 RHS
  • 可同时使用这两种缩写

语法中的变量命名

• 输入和输出：使用帮助文本大小写 ——全小写名称改为全大写；含有任意大写字母、数字或下划线的名称保持原样 示例：data → DATA、method → METHOD、result → RESULT、 depth → DEPTH、obj → OBJ、tf → TF 但 filePath → filePath、queryPoints → queryPoints、 startSample → startSample、maxMemory → maxMemory、 otherBuffer → otherBuffer （这些名称含有大写字母，因此保持原样）
• 正文中引用其他函数时：使用帮助文本大小写；同一文件夹中的函数不得使用完全限定名称
• 通用逻辑输出：使用 TF
• 通用数据：使用单个大写字母（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.

• 语法中的标志名称使用全大写
• 允许的值使用双引号括起
• 值在 % 后缩进七个空格（即 % ）
• 值与描述之间用 -（空格-短横线-空格）分隔
• 较短的值后补空格，使短横线垂直对齐
• 在描述开头使用 (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）
• 代码在 % 后缩进七个空格（即 % ）
• 不得使用控制流（for、if、while）
• 复制到命令窗口后必须能够运行
• 每个示例的代码不超过 10 行
• 多个示例之间用一个空白的 % 行分隔
• 不要为示例编号——在标题行使用文字标签
• 使用行内 % comments 注释代码，不要在代码行之间添加正文

See Also 行

%
%   See also readtable, griddedInterpolant, pdist2

• 前面需有一个空白的 % 行
• 以 % See also 开头（三个空格缩进）
• 名称使用其在 MATLAB 路径中出现的原始大小写拼写（例如 readtable、griddedInterpolant、pdist2） — See Also 名称不要使用帮助文档中的大小写形式
• 使用能够解析的最短名称。MATLAB 路径上不属于任何包的函数可使用裸名称。其他包中的函数 必须使用完全限定名称（例如 pkg.subpkg.funcName）。同一文件夹（同一包级别）中的函数使用裸名称 — 它们 可相互解析
• 不要引用私有方法或私有函数 — 无法通过 help 访问它们；即使使用完全限定名称，也只能在类内部访问。在 @class 文件夹中，除类构造函数之外的所有文件都是方法；引用前请检查其 Access
• @class 文件夹中的方法应添加 See Also 行，引用类本身以及该类相关的公共方法或属性，使用未限定名称（例如 ClassName、methodName、 propertyName）。不要引用其他私有方法
• 用逗号和空格分隔
• 末尾不要加句号
• 包含 2 到 7 个项目
• 不要添加说明 — 只写名称
• 如果该行超过 75 个字符，请在逗号处换行：

  %   See also readtable, readtimetable,
  %   griddedInterpolant, scatteredInterpolant
  

---

Note 部分

%
%   Note: FUNC is in the Signal Processing Toolbox

• 前面需有一个空白的 % 行
• 以 % Note: 开头
• 函数使用其 H1 大小写形式
• 产品使用全称
• 末尾不要加句号

---

版权行

版权行特指符合以下格式的注释：

%   Copyright YYYY

该行以 % 开头，后跟空格，再跟完整单词 Copyright，然后是四位数年份或年份范围（例如，2024 或 2020-2025）。其他仅在函数名或说明中包含“copyright”一词的注释，不属于版权行。

• 版权不属于帮助文本
• 如果文件中存在版权注释，请确保它出现在帮助块之后，并用一个空行隔开（只有换行，不含 %）
• 此空行会终止帮助块；MATLAB 的 help 命令在遇到第一个非注释行时停止读取
• 版权行的缩进必须与上方的帮助注释一致
• 不要添加、删除或修改版权 — 只在需要时移动

---

类帮助

对于 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: — 使用单词 functions，不要使用 methods（与 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 文件夹文件中的方法）根据访问级别遵循以下规则：

公共方法需要完整的函数帮助文本：

• 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

受保护和私有方法只需要 H1：

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

以下情况无论访问级别如何，都只需要 H1：

• 属性 getter/setter（get.Prop、set.Prop）
• 构造函数（类级帮助文本已涵盖构造方式）
• 无实际操作的方法（空方法体）

重写方法和帮助继承：

当子类重写超类方法时，如果重写方法没有帮助文本，MATLAB 会继承超类的帮助文本。利用这一点可以避免重复：

• 省略帮助文本：重写方法执行相同操作（实现不同）
• 编写帮助文本：仅当契约发生变化时（输入/输出不同）

超类帮助文本应尽量通用——描述做什么，而非如何做。

本地定义方法的帮助文本缩进应与方法体一致 （通常为 12 个空格，若 function 关键字缩进 8 个空格）。

单独文件（@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. 确定文件类型：函数、类定义或脚本
4. 如果函数包含 arguments 块，请读取该块以确定必需、可选和名称-值参数
5. 分析签名、输入、输出和行为
6. 按照上述所有规则起草帮助文本
7. 对于类定义文件：检查每个公共属性是否有注释。为缺少注释的属性添加后缀注释——起草时主动完成，无需等用户提出要求
8. 验证：从 % 起算，每行不超过 75 个字符；节顺序正确；缩进正确
9. 向用户展示草稿
10. 获得批准后，使用 Edit 在文件中插入/替换帮助文本

---

版权所有 2026 The MathWorks, Inc.