Learn more about MATLAB

Providing Your Own Help and Demos

On this page…
Overview of Help and Demos for Files You Create Creating Help for Your M-Files Providing a Help Summary for Your M-Files Providing Help for Classes You Create

Overview of Help and Demos for Files You Create

You can provide help and demos for the files you create that are like the help and demos MATLAB provides. The information aids you and other users you share your files with.

There are different types of help you can provide.

Type of Help	Description	See
M-file	Provide formatted comments at the start of an M-file. View the help comments by running help filename. Easy to provide. Easy to use. Suited for individual M-files.	Creating Help for Your M-Files
Contents.m file	Provide a summary M-file for all files in a folder. View the summary by running help foldername. Allows you to provide a version number that users can access. Easy to provide. Easy to use. Suited for a collection of M-files.	Providing a Help Summary for Your M-Files
MATLAB class files	Provide help in the M-file for classes you create, and optionally for the class methods, and properties and events. View the help by running doc classname. Easy to provide. Easy to use.	Providing Help for Classes You Create
Documentation in the Help browser	Provide HTML documentation, and optionally a search database, for use in the Help browser. View the documentation using the Contents pane in the Help browser, and optionally using search. More effort than providing help in M-files. Supports graphics, images, stylized text, and page formatting. Suited for how-to and conceptual information that helps others run your files.	Providing Your Files in the Help Browser
Demos in the Help browser	Provide demos, such as published M-files, for access from the Help browser. View the demos using the Contents pane in the Help browser. Can be generated from M-files. Support graphics, images, stylized text, and page formatting. Suited for explaining how a file works, step-by-step.	Providing Your Files in the Help Browser

Back to Top

Creating Help for Your M-Files

Provide help for the M-files you create that is the same as the help for M-files provided with MATLAB.

Access the help using the help function.

Creating M-File Help for Your Files

To create the help, provide comments on contiguous lines of the M-file:

1. Open the M-file and go to the second line of a function or the first line of a script.

2. Enter the first help comment line, called the H1 line: enter a comment symbol, %, followed by the function name and the purpose of the function.

   MATLAB uses this first help comment line, the H1 line, in other ways, such as in the Current Folder browser description.

3. Continue entering help comments on the following lines.

4. Enter the See also line with the names of related functions.

   • To include an overloaded function, preface the function name with the partial path, using a forward slash.

   • If there are no related functions, do not include a See also line.

   When you run help for the function, MATLAB displays the functions in the See also line as links. The functions must have M-file help and be in the current folder or in a folder on the search path.

5. End the help section, use a blank line or an executable statement.

Be consistent in how you structure your help. For example, follow the style that MATLAB uses. For examples, look at the MATLAB M-files you are familiar with.

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

Example of M-File Help for a User-Created File

For example, for collatz.m, enter:

function sequence=collatz(n)
% COLLATZ Collatz problem. Generate a sequence of integers resolving to 1
% For any positive integer, n:
% 	Divide n by 2 if n is even
% 	Multiply n by 3 and add 1 if n is odd
% 	Repeat for the result
% 	Continue until the result is 1
%
%   See also COLLATZPLOT, LENGTH, MYFILES/LENGTH.

sequence = n
...

When you run help collatz, MATLAB displays

COLLATZ Collatz problem. Generate a sequence of integers resolving to 1
For any positive integer, n:
    Divide n by 2 if n is even
    Multiply n by 3 and add 1 if n is odd
    Repeat for the result
    Continue until the result is 1

See also collatzplot, myfiles/length.

Back to Top

Providing a Help Summary for Your M-Files

Provide a summary file for your own collection of M-files using the same method as MATLAB. In MATLAB, for each folder containing M-files, there is a Contents.m file that lists the functions in the folder and a brief description.

Running help foldername displays the information in the Contents.m file. It includes links to help for all the functions. Running helpwin foldername displays the same information in the Help browser.

Create your own Contents.m files:

• Refer to a Contents.m file provided with MATLAB as an example.

• Use the Displaying and Updating a Report on the Contents of a Folder to help you create and maintain your Contents.m files.

• Provide version information in the first two lines of the Contents.m file:

       % Toolbox description
       % Version xxx dd-mmm-yyyy

  Do not include any spaces in the date and use a two-character day, for example, 02-Sep-2008. Use the ver function to get the information.

Back to Top

Providing Help for Classes You Create

If you create your own MATLAB classes, provide help (comments) in the class definition M-file.

Provide help in a comment line directly following the classdef statement, or in the comment line directly following the constructor method for the class. Optionally, provide additional help comments in the classdef file for other methods, and for properties and events.

To view the help, run:

doc classname

The resulting HTML page displays in the Help browser. It provides a convenient summary of the details, properties, methods, and events for the class. It includes links to descriptions and help for any super classes, and a link to view the code.

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. To view the help, click the class name link below the toolbar.

Example of Help for a User-Created Class

The example shows help for a user-created class M-file, sads.m, 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: click 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.

To see more information for the steer method, click the steer link under "Method Summary" in the sads help page, or run doc sads.steer.

Open the sads M-file by clicking the View code for sads link at the top of the sads help page.

Create an instance of the sads object, sensorArray, and view it in the Variable Editor. To view the sads help in the Help browser, click the sads link in the Variable Editor.

Back to Top

Getting Help and Demos for Files Created By Users

Providing Your Files in the Help Browser

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS