Docstring Conventions
Introduction
This document documents the semantics and conventions associated with MATLAB docstrings.
This document was adapted from PEP 257.
Some conventions were adopted from the MathWorks, Inc.
Rationale
The aim of this document is to standardize the high-level structure of docstrings: what they should contain, and how to say it (without touching on any markup syntax within docstrings). The document contains conventions, not laws or syntax.
- "A universal convention supplies all of maintainability, clarity, consistency, and a foundation for good programming habits too. What it doesn't do is insist that you follow it against your will. That's Python!"
- —Tim Peters on comp.lang.python, 2001-06-16
If you violate these conventions, the worst you'll get is some dirty looks. But some software (such as the Docutils docstring processing system) will be aware of the conventions, so following them will get you the best results.
Specification
What is a Docstring?
A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition.
All modules should normally have docstrings, and all functions and classes exported by a module should also have docstrings. Public methods should also have docstrings.
Two types of docstrings may be extracted by software tools:
- String literals occurring immediately after a simple assignment at the top level of a module, class, or method are called "attribute docstrings".
- String literals occurring immediately after another docstring are called "additional docstrings".
There are two forms of docstrings: one-liners and multi-line docstrings.
One-line Docstrings
It is recommended to construct the first comment block in the .m file as the help information. So that help name will show this information.
% Do something and return something.
function foo = function_name(var)
foo = 0;
end
Notes:
- There's no blank line either before or after the docstring.
- The docstring is a phrase ending in a period. It prescribes the function or method's effect as a command ("Do this", "Return that"), not as a description; e.g. don't write "Returns the pathname ...".
Multi-line Docstrings
Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a more elaborate description. It is important that the summary line fits on one line. The summary line should follow just a single % and no space. For each line of the more elaborate description, use 3 spaces after the single % as the first indentation level, and use extra 4 spaces as a deeper indentation level. There's no blank line before the docstring, but there's one blank line after the docstring. Here we adopted some conventions of the MathWorks, Inc.
The docstring of a script (a stand-alone program) should be usable as its "usage" message. Usage messages can be fairly elaborate (several screens full) and should be sufficient for a new user to use the command properly, as well as a complete quick reference to all options and arguments for the sophisticated user.
The docstring for a module should generally list the classes, exceptions and functions (and any other objects) that are exported by the module, with a one-line summary of each. (These summaries generally give less detail than the summary line in the object's docstring.) The docstring for a package should also list the modules and subpackages exported by the package.
The docstring for a function or method should summarize its behaviour and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable). Optional arguments should be indicated. It should be documented whether keyword arguments are part of the interface.
The docstring for a class should summarize its behaviour and list the public methods and instance variables. If the class is intended to be subclassed, and has an additional interface for subclasses, this interface should be listed separately (in the docstring). The class constructor should be documented in the docstring for its init__ method. Individual methods should be documented by their own docstring.
If a class subclasses another class and its behaviour is mostly inherited from that class, its docstring should mention this and summarize the differences. Use the verb "override" to indicate that a subclass method replaces a superclass method and does not call the superclass method; use the verb "extend" to indicate that a subclass method calls the superclass method (in addition to its own behaviour).
Do not use the convention of mentioning the arguments of functions or methods in upper case in running text. MATLAB is case sensitive and the argument names can be used for keyword arguments, so the docstring should document the correct argument names. It is best to list each argument on a separate line. For example:
% encoding: utf-8 (if necessary)
% MATLAB Version 2012a (if necessary)
%
%Form a complex number.
% z = complex(real, imag) forms a complex number z.
% real -- the real part of z
% imag -- the imaginary part z
%
% Support vectorized patameters.
% Author:
% name 1 (Chinese name) <email 1>
% name 2 <email 2>
%
% Copyright (c) 2012 name 1, 2013 name 2
%
% Permission is hereby granted, free of charge, to any person obtaining a copy
% of this software and associated documentation files (the "Software"), to deal
% in the Software without restriction, including without limitation the rights
% to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
% copies of the Software, and to permit persons to whom the Software is
% furnished to do so, subject to the following conditions:
%
% The above copyright notice and this permission notice shall be included in
% all copies or substantial portions of the Software.
%
% THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
% IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
% FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
% AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
% LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
% OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
% SOFTWARE.
function z = complex(real, imag)
z = real + imag.*i;
end
References
- PEP 257, Docstring Conventions, David Goodger and Guido van Rossum.
- MATLAB Documentation Center
Copyright
This document has been placed in the public domain.