Templates for documentation comments

[SeSodesa]

We should probably settle on the appearance of our documentation comments, so that our documentation looks uniform within the bounds set by the Matlab documentation tools (functions | classes). For example, for functions the structure of the help could be roughly as follows:

function output_argument = function_name(input_argument)

    %
    % function_name
    %
    % A brief description of the role of the function.
    %
    % ────────────────────┤  Inputs  ├────────────────────
    %
    % - input_argument
    %
    %   Input argument description.
    %
    % ────────────────────┤  Outputs ├────────────────────
    %
    % - output_argument
    %
    %   Output argument description.
    %

    arguments

        input_argument (Size) Type { Validation } = default

    end

    % Function code starts here.

    ...

end % function

Notice the additional lines above the function name and below the last line in the documentation comment. Matlab does not trim these when a user runs

>> help function_name

on the command line, which results in a more pleasant appearance. The help text is not printed directly below the command that was just run, nor just above the next prompt, making it easier for the eyes.

Class documentation should probably be similar, but the top level description should only provide a brief description, and the individual properties and methods should get their own documentation comments:

classdef ClassName

    %
    % ClassName
    %
    % Brief description of the class.
    %

    properties

        %
        % ClassName.property_name
        %
        % A description of the property goes here.
        %
        property_name (Size) Type { Validation } = default

    end % properties

    methods

        function self = ClassName(input_arguments)

            %
            % ClassName.ClassName
            %
            % The constructor of this class.
            %
            % ────────────────────┤  Inputs  ├────────────────────
            %
            % - input_arguments
            %
            %   Input argument description.
            %
            % ────────────────────┤  Outputs ├────────────────────
            %
            % - self
            %
            %   An instance of this type or class.
            %

            % Constructor code starts here.

            ...

        end % function

        function [self, other_outputs] = some_other_method(self, other_inputs)

            %
            % ClassName.some_other_method
            %
            % A brief description of the role of the method.
            %
            % ────────────────────┤  Inputs  ├────────────────────
            %
            % - input_argument
            %
            %   Input argument description.
            %
            % ────────────────────┤  Outputs ├────────────────────
            %
            % - output_argument
            %
            %   Output argument description.
            %

            % Method code starts here.

            ...

        end % function

    end % methods

end % classdef

I am putting these here, so that they could be copied and pasted, if one wishes to write a new function or class. We could also provide a function to automate generating a new function or class skeleton file in the project.