matlab-write-help

## When to Use

- Writing help text for a new MATLAB function, class, or script
- Rewriting or improving existing help text that is incomplete or non-conforming
- Reviewing help text for standards compliance
- Adding help to methods in a classdef file
- Generating property comments for a class

## When NOT to Use

- Writing general documentation or README files (not help comments)
- Generating code — this skill only produces help text
- Working with non-MATLAB languages
- Writing MATLAB Live Script markup (use plain-text-live-code guidelines instead)

## Task

Resolve `$file` to an M-file path and generate complete, standards-compliant MATLAB help text for it. If the file already has help text, improve it to meet the standards below. Present the proposed help text to the user for review before modifying the file.

## Standards for MATLAB Help Text

All rules below are mandatory. Violating any of them produces non-conforming help.

### General Rules

- Help begins on line 2 (after `function` or `classdef` line) for functions/classes
- Help begins on line 1 for scripts or built-in sidecar files
- Help comments must match the indentation of the body code.
  Look at the first non-comment content after the help block to
  determine the indentation level:
  - For `classdef` files: the body is `properties`/`methods` blocks,
    which are always indented 4 spaces → class help at 4 spaces
  - For `function` files: look at the first executable statement.
    If at column 1, help at column 1; if at 4 spaces, help at 4 spaces.
    Example at 4-space indent:
    ```
    function result = myFunc(x)
        %myFunc - Brief description
        %   RESULT = myFunc(X) does something with X.
        result = x + 1;
    end
    ```
  - For inline methods in classdef: if body is at 12 spaces, help at
    12 spaces
  Both styles are valid for top-level functions — match whichever one
  the file already uses. Do NOT change the file's indentation style
- No comment line may exceed 75 characters measured from the `%` onward
  (i.e., 75 characters of comment content including the `%` itself).
  If the `%` is indented, the total line width is indent + 75.
  Syntax lines are exempt (see below).

  Max column = indent + 75 (e.g., indent 12 → max col 87).
  Count from the `%`, not from column 1.
- No tabs — spaces only
- No trailing whitespace
- No block comments (`%{ %}`) — only `%` line comments
- No hardcoded links to documentation or webpages
- No `'href="matlab:'` evaluation links

### Section Order

1. H1 Line
2. Release Compatibility (if applicable)
3. Syntax Paragraphs
4. Example (optional)
5. See Also line
6. Note (optional)

A blank line (no `%`) separates help from the copyright line.

---

### Help Casing

When function or class names appear in help text (H1 lines, syntax
paragraphs, prose references, and See Also lines), they use **help
casing** to distinguish them from ordinary words. The `help` command
renders help-cased names as bold or hyperlinks.

Rules:
- Names that are entirely lowercase letters [a-z] are uppercased
  (e.g., `sort` → `SORT`, `magic` → `MAGIC`)
- Names that start with an uppercase letter but the remaining letters
  are all lowercase are also uppercased
  (e.g., `Table` → `TABLE`, `Handle` → `HANDLE`)
- Any other name (mixed case, digits, or underscores) keeps its exact
  original casing — do NOT uppercase it
  (e.g., `readTable` → `readTable`, `XMLReader` → `XMLReader`,
  `image_resize` → `image_resize`, `pdist2` → `pdist2`)

---

### H1 Line

```
%FUNCNAME - Brief description without a period
```

- Begins with `%` immediately followed by the function name in help
  casing (no space after `%`)
- Do NOT include namespace or class name
- ` - ` (space-dash-space) separates the name from the description
- Do NOT end with a period
- Description should be a brief summary of the function's purpose

---

### Syntax Paragraphs

```
%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.
```

Note: no blank `%` line between the H1 and the first syntax paragraph.

- One paragraph per syntax
- Each paragraph begins with the syntax it describes followed by a
  lowercase verb — the syntax reads as the subject of the sentence
  (e.g., `%   B = FUNC(A) does...` not `%   B = FUNC(A) Returns...`)
- Function name uses help casing
- All lines indented with three spaces after `%` (i.e., `%   `)
- No blank `%` line before the first syntax paragraph
- A blank `%` line separates each syntax paragraph
- Input ordering in syntax: Required → Optional → Name-Value
- The first syntax paragraph describes all required inputs only
- Each optional input gets its own syntax paragraph
- The first syntax paragraph shows only the primary output. Additional
  outputs are introduced one at a time in later syntax paragraphs —
  never jump from one output to all outputs at once. Each new output
  gets its own paragraph. This mirrors the input layering — start
  simple, add complexity one piece at a time. Examples:

  Two outputs — one additional paragraph:
  ```
  %   IDX = FINDNEAREST(POINTS,TARGET) finds the nearest point.
  %
  %   [IDX,DIST] = FINDNEAREST(...) also returns the distances.
  ```

  Three outputs — two additional paragraphs (not one):
  ```
  %   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.
  ```
- Use `...` to abbreviate previously-described arguments when an optional
  applies to all prior syntaxes
- If a syntax exceeds 75 characters, the syntax itself is exempt from
  wrapping — keep it on one line. The description text that follows
  wraps normally starting on the next line. To shorten long syntaxes:
  - Abbreviate the LHS with `[...]` when outputs