Help Block

The help block is the first commented lines in the file and should be directly after the declaration at the very top of the file. The help block is also how the file makes its first impression. Unfortunately, even MathWorks does not set an entirely consistent example. In general in the help block:

• Everything should be indented (% in column 1, first character in column 5).
• Use complete sentences; end sentences with punctuation.
• Write the file name in all caps in every instance. MATLAB will automatically make it lowercase and bold when displayed using the help function.

The following order of information for a help block is recommended:

Brief description

Write the FILENAME, i.e. the function name or class name, written in all caps, followed by a few (ideally only one) sentences briefly describing what the module does.

Try to put some keywords in the first line. This, along with a descriptive function name, will help support the lookfor function.

The brief description should not be indented (the only exception to the indentation rule above). Put the % in column 1 and the first character of each line of the brief description in column 3.

Follow the description header with a blank line (optional for short descriptions or help blocks).

Full-syntax call

That is, [allPossibleOutputs] = functionname(allPossibleInputs). If a radically different syntax is allowed, it should be listed directly below. For example:

%   [output1, output2] = functionname(input1, input2, input3)

%   [outputStruct] = functionname(inputStruct)

In some cases it may be appropriate to omit this entry and instead use a full-syntax call in lieu of using only FILENAME in the first line of the help block (see "brief description" above).

Follow the full-syntax call with a blank line.

Input & output explanations

Alternative 1: List of inputs and outputs

List inputs and outputs. The variable names are the ones declared above in the full-syntax declaration. Each variable description should line up vertically and should wrap to this location. Separate the variable names from their descriptions with "- " as shown below.

%   variableName - Brief description.

%   anotherVar   - Begin descriptions with a capital letter. For really

%                  long descriptions, wrap to the location of the first

%                  character.

Input/output descriptions should include information on the type of variable expected/generated. If an input is not required, be sure to include what the default behavior is, if applicable, in the description.

Structuring the list with headings (e.g. Inputs: and Outputs:), indentation, and/or white space is often appropriate.

Alternative 2: Expanded-syntax style

As an alternative to simply listing inputs and outputs after a full-syntax call, use the expanded-syntax style of explaining input and output arguments (more common in MathWorks help blocks):

%   output1 = functionname(input1) does this and that.

%

%   output1 = functionname(input1, input2) does this and that, with a

%   restriction on that.

%

%   output1 = functionname(input1, input2, input3) does this, that, and the

%   other.

%

%   [output1, output2] = functionname(...) gives me and extra thing.

Follow the input/output explanations (either alternative) with a blank line.

Notes

Put in any necessary notes on usage, limitations, assumptions, methods, dependencies, etc. Separate notes with blank lines. To direct the user to more information, html-style hyperlinks can be inserted (<a href="http://www.mathworks.com/matlabcentral/">Link text</a>).

Be sure to either in the notes section or in the input/output explanations to communicate to the user the degree of vectorization of the module.

Examples

Put examples in the form

%   Example 1: Brief but complete imperative sentence describing what the

%   example accomplishes.

%     example code line

%     another example code line

%

%   Example 2: ...

The lines of the example code itself should be indented under the description two to four spaces. Separate examples with blank lines.

Methods and properties

For a class, list the methods and properties (usually in that order) using the same format as with input & output explanations alternative 1. Again, structuring the list with headings and white space is usually appropriate, especially to separate methods from properties.

See also statement

The usefulness of the see also should not be underestimated. Be liberal in the number of entries you include. If it is unlikely that an entry will be on the user's path, include a URL directly below where it can be downloaded (text starting with http:// with automatically be made into a hyperlink). Conclude the see also statement with a period and follow the see also statement with a blank line.

Repeat of full-syntax call

If the help block is longer than 25-30 lines, consider inserting a repeat of #2: full-syntax call. This prevents the need to scroll up the command window if all the user wants is a reminder on syntax.

Showdemo

If you published further documentation using the MATLAB publisher and the resulting html file is in the right place with the right name (mfilelocation/html/mfilename.html), the help function will automatically display a link.