Skip to content

Function Documentation

Jump to bottom Edit New page
Jennifer Maxwell edited this page Aug 20, 2019 · 17 revisions

Introduction

Much of the isetbio codebase is in the form of functions. This page describes how we document those.

See Documentation & Formatting for links to documentation of other code file types (objects, methods, tutorials, etc.)

For functions, we adopt certain formatting and style of the header comment for functions within the ISETBIO scope. The header comment has both required and optional headings. We also try include short fully executable examples of how the function is used in block comments at the top of the source code. These are placed in an (optional) Examples section of the code after the Required Headings. The developers often return to view these examples, which may be selected and executed from the Matlab editor, and we believe the examples will be useful to others. The Required Headings indicates indicate whether the code contains such examples.

Required Headings in Header Comment

These headings and their content are intended to clarify the purpose of functions and how to use them.

  • Short Description - This is a one-line (<75 character) quick summary of the function's general purpose
  • Syntax - Show an example usage of the function call. Body text is indented 3 spaces from the comment marker
  • Description - A detailed description of the function, its intended uses, etc. Body text is indented 4 spaces from the comment marker for first-level.
  • Inputs - A list of all of the required inputs for the function, as well as explanations to what they represent. The line items are indented a minimum of 4 spaces from the comment marker. The definitions are separated from their names by a dash, and the left margin of the text is aligned for all definitions based off the length of all of the input/output variables, with few exceptions. The definitions are required even if you feel the variable name makes the input's definition obvious.
  • Outputs - A list of all of the outputs of the function, as well as explanations to what they represent. The line items are indented a minimum of 4 spaces from the comment marker. The definitions are separated from their names by a dash, and the left margin of the text is aligned for all definitions based off the length of all of the input/output variables, with few exceptions. The definitions are required even if you feel that the variable name makes the output's definition obvious.
  • Optional key/value pairs - This section is for optional variables and/or key/value pairs, and follows the same guidelines as the inputs and outputs sections (4 spaces indented, etc...). If there are no pairs, use "None." please. The keys will be encapsulated in single quotes and the explanation of the keys should contain the expected value's type. e.g. 'myKey' - String describing what the key unlocks. Possible values are 'house', 'office', 'garage'. Default is 'house'

Example header comment with the required headings:

function myRes = calcDiff(var1, secondVar, signAgnostic)
% Return the difference of the provided variables
%
% Syntax:
%   myRes = calcDiff(var1, secondVar, signAgnostic)
% 
% Description:
%    Find the difference between two integer variables, and return the value. 
%    If signAgnostic is true, then the function will return the absolute value of the
%    subtraction of the second variable from the first. Else, a
%    negative value may be returned if the second variable is
%    larger than the first.
%
% Inputs:
%    var1         - Integer. First integer value for the calculation
%    secondVar    - Integer. Second integer value for the calculation
%    signAgnostic - Boolean . A boolean indicating whether or not to ignore
%                   a possible negative resulting sign of the result.
%
% Outputs:
%    myRes        - Integer. The calculated difference between the two
%                   provided integer values. 
%
% Optional key/value pairs:
%    None.
%

end

Examples

Many of the functions have an extensive set of examples of actual functioning uses of the function. Examples are encapsulated in block comments, as shown below where we illustrate the format of the Optional Headings. Written using this block comment format, the examples can be run by a copy-and-paste directly from the code.

The Examples section is separated from the rest of the sections by a preceding blank line. For this reason, the Examples do not show up immediately in help or doc calls. We made this decision because the examples can be lengthy and not all of them are immediately helpful to the function's significance.

Examples are the last section of a heading, always, and are removed from previous sections by a preceding blank like. Each example is encased in a set of block comments %{ %}. No text can be on either the opening or closing lines.

Please remember to comment at the end of the Required Headings (see above) that there are examples, if there are.

Optional Headings in the Header Comment

These headings are nice to have, but not required.

  • References - This section is for citations. Links and titles are very useful, and possibly more thorough explanations if you feel you cannot adequately cover everything in the description section. Aside from being 4 spaces indented from the comment marker, we have not established anything too restrictive about formatting for this section
  • Notes - This is one location to list known issues, complications, or shortcomings of existing code. It is also a good place to record TODO lists. This section is typically composed of a bulleted list that is denoted by a comment marker, 4 spaces, and then an asterisk. Notes about function details and existing usage should be kept in the description section. We also try to include the initials of the person who wrote the note.
  • History - This section records a running change of who edited your file, when, and with a small summary of the changes made. The format is The comment marker, 4 spaces, the date in MM/DD/YY, two spaces, the initial(s) of the editors, two spaces, and the change summary. This section is also separated from the rest of the header like the examples section (with a line of white space). This section would be placed before the examples section.
  • See Also - This section is for references to other MATLAB functions/classes by name. The spacing for this section is 3 spaces after the comment marker. This would be the final section in the main body of the header.

An example header comment including optional headings:

     function myRes = calcDiff(var1, secondVar, signAgnostic, varargin)
     % Return the difference of the provided variables
     %
     % Syntax:
     %   myRes = calcDiff(var1, secondVar, signAgnostic, [varargin])
     % 
     % Description:
     %    This function is intended to find the difference between two
     %    integer variables, and return the value. If signAgnostic is
     %    true, then the function will return the absolute value of the
     %    subtraction of the second variable from the first. Else, a
     %    negative value may be returned if the second variable is
     %    larger than the first.
     %
     % Inputs:
     %    var1         - Integer. First integer value for the calculation
     %    secondVar    - Integer. Second integer value for the calculation
     %    signAgnostic - Boolean . A boolean indicating whether or not to ignore
     %                   a possible negative resulting sign of the result.
     %
     % Outputs:
     %    myRes        - Integer. The calculated difference between the two
     %                   provided integer values. 
     %
     % Optional key/value pairs:
     %    'noInt'      - Boolean. A boolean indicating if you want a double
     %                   returned instead of an integer. Default is false.
     %
     % Examples are included within the code.
     %
     % Notes:
     %    * [Note: JNM - This is my example note] <- format for within
     %      body of function/class too!
     %    * TODO:
     %          i) First item
     %          ii) Second item
     %    * TODO: re-implement signAgnostic as an optional parameter,
     %      with a default value of 0 (false)
     %
     % See Also:
     %    addMe, mySubtract, calcSum
     %

     % History:
     %    11/15/17  jnm  Created & formatted

     % Examples:
     %{
         myDiff1 = calcDiff(4,5,false)  % returns -1
     %}
     %{
         myDiff2 = calcDiff(4,5,true)  % returns 1
     %}
     %{
         myDiff3 = calcDiff(4,5,true,'noInt',true)  % returns 1.00
     %}

    end

Spacing requirements summary:

  • General:
    • Line length is capped at 75 characters.
  • Required Sections:
    • Short description has no header, is one space offset from comment marker
    • Syntax body text is 3 spaces offset from comment marker
    • Description body text is 4 spaces offset from comment marker
    • Inputs, typically an unmarked list, with the body text is 4 spaces offset from comment marker. Left align variable descriptions based on length of longest variable name. Specify what the input is (string, row vector, matrix, etc.). If the input is optional provide the default value.
    • Outputs, typically an unmarked list, with the body text is 4 spaces offset from comment marker. Left align variable descriptions based on length of longest variable name. Specify what the output is (string, row vector, matrix, etc.)
    • Optional key/value pairs are typically an unmarked list, with the body text is 4 spaces offset from comment marker. Left align variable descriptions based on length of longest variable name. For values, specify what it is (string, row vector, matrix, etc.) and provide default value.
  • Optional Sections:
    • References body text is 4 spaces offset from comment marker
    • Notes, typically a bulleted list, with the asterisk marker 4 spaces offset from comment marker. The Text is one space offset from that. Individual notes follow the format [Note: XXX - Body] where XXX are the initials of the note's author and Body is the body text of the notes.
    • History has dates in the format MM/DD/YY offset from the comment marker by 4 spaces, then commenting individual's initials offset by 2 spaces, and the body of the change summary offset by an additional 2 spaces.
    • See Also body text is 4 spaces offset from comment marker
Add a custom footer

Clone this wiki locally