MATLAB®

Help for the Files You and Other Users Create

About Help for User-Created Files

You can provide help for the files you create using MathWorks products. The help reminds you about a function, but also aids other users who might access your files. The type of help to provide depends primarily on what you are providing and the number of users you are providing the files to.

• For a few M-files that only you or a few others use, providing help in the M-file is probably sufficient.

• If you maintain many M-files, you can use Contents files to help you and other users utilize the help.

• For MATLAB classes you create, you and other users can access the M-file help in the Help browser.

• If you provide your files to many other users, you might want to provide HTML documentation and demos that users can access in the MATLAB Help browser.

Back to Top

Help for M-Files Created by Users

The help system in MATLAB, like MATLAB itself, is highly extensible. You can write help descriptions for your own M-files and toolboxes using the same self-documenting method that MATLAB M-files and toolboxes use. This is helpful if you share your files with other users. Similarly, if you use M-files created by other users, you will benefit if they provide M-file help in the files.

Create self-documenting online help for your own M-files by entering text on one or more contiguous comment lines, beginning with the second line of the file (first line if it is a script). For example, the function soundspeed.m begins with

function c=soundspeed(s,t,p)
% soundspeed computes the speed of sound in water
% where c is the speed of sound in water in m/s

t = 0:.1:35;

When you execute help soundspeed, MATLAB displays

soundspeed computes the speed of sound in water
where c is the speed of sound in water in m/s

These lines are the first block of contiguous comment lines. After the first contiguous comment lines, enter an executable statement or blank line, which effectively ends the help section. Any later comments in the M-file do not appear when you type help for the function.

The first comment line in any M-file (the H1 line) is special because the Contents.m file uses it to provide a brief summary of the function's purpose. The H1 line should contain the function name and a brief description of the function. For the soundspeed example, the H1 line is

% soundspeed computes speed of sound in water

Use the Generating a Summary View of the Help Components in M-Files to help you create and manage M-file help for your own files.

Back to Top

Contents Files for Your Own M-File Directories

A Contents.m file is provided for each M-file directory included with the MATLAB product. With an up-to-date Contents.m file, running help toolboxname displays the functions in the M-file directory, along with brief help (the H1 line) for each function. If you create directories in which to store your own M-files, it is a good practice to create and maintain Contents.m files for them. Use the Displaying and Updating a Report on the Contents of a Directory to help you create and maintain your own Contents.m files.

Back to Top

Help for User-Created Classes

If you create your own MATLAB classes and provide help (comments) for the properties and methods in the class definition M-file, you can view the class help in the Help browser with the doc function, as in

doc classname

The resulting HTML page provides a convenient summary of the details, properties, methods, and events for the class, and includes links to descriptions as well as to help for any super classes. You can open the classdef M-file in the Editor from the help page by clicking the View code for classname link at the top of the page in the Help browser.

To go directly to help for a method, run

doc classname.methodname

Similarly, to go directly to the help for properties and events, use doc with the dot notation, providing the property name or event name after the dot.

When you create an instance of a class and open the object in the Variable Editor, you can access the HTML help for the class by clicking the class name link below the toolbar. This provides the same information as when you run doc classname.

Example of Help for a User-Created Class

This example shows help for a user-created class M-file, sads.m, which is provided with MATLAB documentation. Run the following statements to use the example.

% Change the current directory to where the example file is located.
cd(fullfile(matlabroot,'help','techdoc','matlab_env', 'examples')
% View help for the file in the Help browser.
doc sads
% For more information, follow links. Or go directly to help, e.g. for the steer method.
doc sads.steer
% To see the help comments in the class M-file, sads.m, click the link in help, or run:
open(fullfile(matlabroot,'help','techdoc','matlab_env', 'examples','sads.m'))
% Create an instance of the sads class.
loadparameters
sensorArray=sads(Data, Wavelength,SampleRate,Spacing,Name);
% Another way to see help for sads is by clicking the classname link in the Variable Editor.
% Open sensorArray in the Variable Editor.
openvar sensorArray

The following illustration shows the help for sads, displayed in the Help browser.

The following illustration shows more information for the steer method, which you can view by clicking the steer link under "Method Summary" in the sads help page, or by running doc sads.steer.

The following illustration shows the sads M-file opened in the Editor, which you can view by clicking the View code for sads link at the top of the sads help page.

The following illustration shows an instance of the sads object, sensorArray, in the Variable Editor. You can click the sads link in the Variable Editor to view the sads help in the Help browser.

Back to Top

Adding Your Own Help Files and Demos in the Help Browser

You can add your own HTML help files and demos so that they appear in the Help browser. For details, see Adding Your Own Toolboxes to the Development Environment (This section is not in the PDF documentation; use the Help browser or documentation on the Web site to access it).

Back to Top

Related Resources

Workspace, Search Path, and File Operations