Help Text and Documenting Code

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The reference material consulted while preparing these pages is listed in the section bibliography.

Written against MATLAB R2026b. The help-text examples below (the function files and the output of help) were run in GNU Octave 11.3.0, which reads % comment blocks as help text in the same way; MATLAB lays the output out differently and adds hyperlinks. The class help, Contents.m, functionSignatures.json and custom-documentation examples were checked against the R2026b reference pages and not run here, because they depend on the MATLAB desktop, doc or a code-suggestion engine.

MATLAB has no separate documentation language. Documentation is a block of ordinary comments placed where help looks for it, so the same file holds the code and the text that explains it. The reward for following a few placement rules is that help, doc, lookfor, the Files panel and the function hints all show your text, exactly as they show it for the functions shipped with MATLAB (see Getting Help and Documentation for the reading side of the same mechanism).

Help comments for functions and scripts

Help text is the first contiguous block of comment lines in a file. For a function file, that block goes immediately below the function line. If the function has an arguments block (see Argument Validation), the help text may also go immediately below that block. For a script it goes at the top of the file. Comments written anywhere else are ordinary comments and are never shown by help.

The documentation’s own example has this shape:

  • The H1 line is the first line of the help text. By convention it begins with the program name in capital letters, followed by a one-line description. The Files panel, help and lookfor all use the H1 line to describe the program.

  • The body follows: the calling syntaxes, what each argument and output means, and any caveats. The convention is to write function names in capitals inside the text so that they stand out in the Command Window.

  • A See also line at the end names related functions. If the named functions are on the search path or in the current folder, help shows each of them as a hyperlink; otherwise it prints the names as written.

  • A blank line without a % ends the help text. Comments after it are not help, so implementation notes can follow safely.

Source: MATLAB documentation: Add Help for Your Program

A documented heatflow function

The heatflow scenario of this section needs a dimensionless number that tells whether an explicit time step is stable. Here it is, with help text, a See also line and an implementation comment that is deliberately separated from the help by a blank line. The file is diffusionnumber.m:

function r = diffusionnumber(alpha, dt, dx)
% DIFFUSIONNUMBER Dimensionless diffusion number of an explicit step.
%   r = DIFFUSIONNUMBER(alpha, dt, dx) returns alpha*dt/dx^2, the number
%   that must stay at or below 0.25 for the explicit 2-D scheme to be stable.
%
%   See also STABLESTEP.

% Implementation note: this comment follows a blank line, so it is not help.
r = alpha*dt/dx^2;
end

Its companion stablestep.m (shown on Getting Help and Documentation) is the function named in the See also line. Calling help diffusionnumber prints the comment block only. Octave 11.3.0 printed this (before a generic Octave footer that MATLAB does not print; MATLAB turns STABLESTEP into a link and, in the reference page’s example, prints function names in lower case):

 DIFFUSIONNUMBER Dimensionless diffusion number of an explicit step.
   r = DIFFUSIONNUMBER(alpha, dt, dx) returns alpha*dt/dx^2, the number
   that must stay at or below 0.25 for the explicit 2-D scheme to be stable.

   See also STABLESTEP.

The implementation note does not appear. In the same run diffusionnumber(1.1e-4, 20, 0.1) returned 0.2200, so a 20 s step on a 0.1 m grid with the diffusivity of the plate is stable. lookfor diffusion found the file by its H1 line; Octave wraps the H1 text across several lines, while MATLAB prints one line per match and shows the H1 line only.

Source: MATLAB documentation: Add Help for Your Program, MATLAB documentation: lookfor

Writing a good H1 line

lookfor keyword searches the H1 lines of user-written files on the path, so the H1 line is the searchable summary of your function. Three habits make it useful:

  • Put the keywords a colleague would search for in the first sentence, not only the function name.

  • Keep it to one line, and do not repeat the syntax in it; the syntax lines come next.

The reference page for lookfor -all documents the wider search only for the reference pages shipped with MATLAB, so rely on the H1 line for your own code.

Source: MATLAB documentation: lookfor

Links inside help text

Help text can contain a hyperlink: wrap an HTML anchor element around the text, with a matlab: statement in the href that runs a command such as web. A statement that runs MATLAB code is clickable only in the MATLAB desktop. It does nothing in a web browser, and a link whose target runs arbitrary code is a reason to read help text of downloaded code before you click it.

Source: MATLAB documentation: Add Help for Your Program

Which help wins

When several programs share a name, help applies the rules of function precedence to decide whose text to show (see Function Precedence and Name Resolution). The Help on Selection command in the editor’s context menu is different: if your file has the same name as a MathWorks function, it always shows the MathWorks documentation. A file that shadows a built-in name therefore shows two different help texts depending on how you ask.

Source: MATLAB documentation: Add Help for Your Program

Help for live functions

A live function (a function in a .mlx file) keeps its help text in a text line placed immediately before the function line, created with the Text button of the Live Editor tab. The text can be formatted, and a See also line must be preceded by a blank text line for the links to display. You can also use comments at the beginning of the file as for a plain function. See Live Scripts and the Live Editor.

Source: MATLAB documentation: Add Help for Live Functions

Folder summaries: Contents.m

A Contents.m file summarises the programs of a folder. It contains only comment lines, and help foldername and doc foldername show it. The format is:

  • the first two lines are headers: a one-line description of the folder, then a version and date line (Version 1.2.0 09-Nov-2022) in which the date must not contain spaces;

  • the following lines list files with a description, optionally in groups introduced by a category line;

  • an optional % See also line at the end, linked in the same way as in function help.

For the heatflow folder it looks like this (not run here; a template-based file from the reference page, adapted):

% Heat-flow helper functions
% Version 1.0.0 22-Oct-2026
%
% Stability
%   diffusionnumber        - Dimensionless diffusion number of an explicit step
%   stablestep             - Largest stable explicit time step

If a folder has no Contents.m, help and doc generate a list of all its program files with a short description for each. To suppress that generated list place an empty Contents.m in the folder; the commands then print only a line saying that the name is a folder. Because the date line is parsed and the file list is typed by hand, a Contents.m goes stale whenever you add or rename a file; keeping it current is part of the release routine of a toolbox (see Toolboxes and Add-On Products).

Source: MATLAB documentation: Create Help Summary Files - Contents.m

Help for classes

For a class, doc ClassName already shows an automatically generated page derived from the class definition: the properties, methods, events and enumerations that are not private, each with its first help line. The comments you write add to that page, and help shows them in the Command Window. The rules, from the reference page, depend on where the comment sits:

Item Where the help text goes

Class

Comment lines immediately after the classdef line. An optional list of the form ClassName Properties: or ClassName Methods: followed by name - description lines turns the names into links to their help.

Method

Comment lines immediately after the function line, as for any function. Display it with help ClassName.method.

Property

Comment lines above the definition (use these for multi-line text), or a single-line comment next to it. The comment above wins when both exist. Display it with help ClassName.property.

Enumeration member

The same two forms as for a property, inside the enumeration block.

Event

The same two forms as for a property, inside the events block.

Applied to the plate class of the heatflow scenario (not run here; see Classdef Basics for the class itself):

classdef Plate
    % Plate  Rectangular plate for the heat-flow model
    %   A Plate holds the material constants and the grid spacing.
    %
    % Plate Properties:
    %    Alpha - Thermal diffusivity in m^2/s
    %    Dx    - Grid spacing in m
    %
    % Plate Methods:
    %    stableStep - Largest stable explicit time step

    properties
        Alpha (1,1) double = 1.1e-4   % Thermal diffusivity in m^2/s

        % Dx - Grid spacing in m
        % The same spacing is used in both directions.
        Dx (1,1) double = 0.1
    end

    methods
        function dt = stableStep(obj)
            % stableStep  Largest stable explicit time step
            %   dt = stableStep(obj) returns Dx^2/(4*Alpha).
            dt = obj.Dx^2/(4*obj.Alpha);
        end
    end
end

help Plate, help Plate.stableStep and help Plate.Dx then show the three blocks. The comment for Alpha sits on the same line as the definition, so it is the single-line form; the comment for Dx is above the definition and may span several lines.

Source: MATLAB documentation: Create Help for Classes

Code suggestions: functionSignatures.json

When you type a call and pause, or press Tab, MATLAB suggests arguments. For a function that has an arguments block, MATLAB takes the suggestions from that block without any extra file. For functions without one, and for argument information beyond what the block states, you describe the signatures in a JSON file named functionSignatures.json.

  • Place it in a folder named resources inside the folder that contains the function. For a class method or a namespace function, put it in the resources folder of the parent folder of the outermost class or namespace folder. One file can describe several functions.

  • The file holds one JSON object: an optional _schemaVersion (a string such as 1.0.0; the current version is 1.0.0, assumed if missing), then one property per function name. Class constructors, methods and namespace functions use the full name, for example myClass.myMethod.

  • Each function maps to a signature object with an inputs array, an optional outputs array and an optional platforms list. The order of the entries in inputs is significant.

  • Each argument object has a required name, a kind and a type. The kind is one of required, ordered or namevalue for the common cases; positional, flag and properties are also available. type names classes and attributes, for example numeric, scalar or >=0, and combines them in lists as described on the reference page.

  • The names need not match the code, but matching the help text is the recommended practice.

  • Custom suggestions are not supported in MATLAB Online.

For the stablestep function (not run here; the structure follows the reference page, the attribute list is an assumption to check with the validator below):

{
  "_schemaVersion": "1.0.0",
  "stablestep": {
    "inputs": [
      {"name": "dx",    "kind": "required", "type": ["numeric", "scalar"]},
      {"name": "alpha", "kind": "required", "type": ["numeric", "scalar"]}
    ],
    "outputs": [
      {"name": "dt", "type": ["numeric", "scalar"]}
    ]
  }
}

If the JSON has syntax errors, MATLAB prints an error in the Command Window when it reads the file. validateFunctionSignaturesJSON (R2018b) checks the file in the current folder, or the files you name, against the JSON schema and the MATLAB signature schema and shows the line of each problem, so run it after every edit.

Source: MATLAB documentation: Customize Code Suggestions and Completions, MATLAB documentation: validateFunctionSignaturesJSON

Publishing documentation

Help text answers "how do I call this". Longer documentation is produced in other ways, which this page only points at:

  • Live scripts and live functions combine code, output and formatted text and can be exported to HTML or PDF; see Live Scripts and the Live Editor.

  • Publishing a plain script turns its code sections and comments into a formatted document with the publish function (publish); see Scripts and Code Sections.

  • Custom documentation for a package of your own can appear in the system web browser next to the MathWorks documentation (not supported in MATLAB Online). It needs HTML help files, an info.xml file that tells MATLAB where they are and what to call them, and a helptoc.xml file with the table of contents, stored with the HTML files. The folder must be on the MATLAB path and outside the MATLAB installation folder. You can write the HTML by hand, export live scripts or publish scripts. The documentation then appears under Supplemental Software on the documentation home page. The reference page gives the full info.xml template.

Source: MATLAB documentation: Display Custom Documentation, MATLAB documentation: Publish and Share MATLAB Code

Common mistakes

Symptom Cause and fix

help myfun prints nothing

The comment block is not directly below the function line (or arguments block), or a blank line or statement separates them. Move the block up.

Help text shows implementation notes

There is no blank line between the help and the notes. End the help block with a line without %.

lookfor does not find the function

The H1 line is missing, or the folder is not on the path. Add a keyword-rich first line and check the path.

help and Help on Selection disagree

The file has the same name as a MathWorks function. Rename it.

A See also name is not a link

The function is not on the path or in the current folder, or in a live function the link line is not preceded by a blank text line.

Suggestions do not appear

functionSignatures.json is not in a resources folder next to the code, or it has errors. Run validateFunctionSignaturesJSON.

help for a folder lists files you do not want shown

There is no Contents.m; add one, or an empty one to hide the list.

Where older books differ

Older books describe the Help browser and the helpdesk command, and show help only for functions. Since R2024b documentation opens in the system web browser (see Getting Help and Documentation). The functionSignatures.json mechanism was introduced with R2018b (validateFunctionSignaturesJSON) and is absent from older books, which also pre-date the class help for properties, enumerations and events. Help text itself, the H1 line and Contents.m are long-standing features that older books describe correctly.

See Also

References