Dev Documentation

PESTO documentation is created from in-source comments and separate Markdown files using mtoc++ and Doxygen.

Creating / updating the documentation

The documentation is (re)created by running MatlabDocMaker.create, which will place the resulting pdf document in /tools.

Comment formatting

For proper automatic generation of the documentation, in-source comments must adhere to a specific format.

General points

• Single line breaks within comments are translated to spaces in the documentation
• Multiple line breaks within comments begin a new paragraph in the documentation
• * can be used to create bullet points
• Be careful with : and * within comments, especially within function parameter documentation (see below)
• If in doubt: check the pdf output
• Check for MatlabDocMaker finished with warnings!, significant parts of the documentation might not have been generated

Matlab functions

Comment-template for Matlab functions:

% [Brief description]
%
% [Full description]
%
% Parameters:
% [requiredParameterName1]: description of required parameter 1
% [requiredParameterName2]: description of required parameter 2
% varargin:
% [optionalParameterName2]: description of optional parameter 1
%
% Return values:
% [returnValueName1]: [Description of return value 1]

Notes:

• [...] are just placeholders, square brackets mark text to be replaced in this template
• This must be placed within the function body (not above)

Matlab classes

Comment-template for Matlab functions:

classdef [classname]
% [Brief description]
%
% [Full description]

properties
    % [Description of property1]
    property1 = defaultValue1;
    
    [...]
end

Notes:

• [...] are just placeholders, square brackets mark text to be replaced in this template
• If the class has non-empty structs as property defaults, description of the fields has to be written above the property definition. No comments are allowed within the struct (although allowed by matlab).
• Do not write default property values in the comments, they will be automatically included by mtoc++/Doxygen
• Do not use %% comments within the class body for structuring, they will be considered to be descriptions of the following class member. If you really need comments for structuring, use HTML type comments such as % <!-- General options -->