Skip to main content
Engineering LibreTexts

5.3: Function Documentation

  • Page ID
    86180
  • \( \newcommand{\vecs}[1]{\overset { \scriptstyle \rightharpoonup} {\mathbf{#1}} } \) \( \newcommand{\vecd}[1]{\overset{-\!-\!\rightharpoonup}{\vphantom{a}\smash {#1}}} \)\(\newcommand{\id}{\mathrm{id}}\) \( \newcommand{\Span}{\mathrm{span}}\) \( \newcommand{\kernel}{\mathrm{null}\,}\) \( \newcommand{\range}{\mathrm{range}\,}\) \( \newcommand{\RealPart}{\mathrm{Re}}\) \( \newcommand{\ImaginaryPart}{\mathrm{Im}}\) \( \newcommand{\Argument}{\mathrm{Arg}}\) \( \newcommand{\norm}[1]{\| #1 \|}\) \( \newcommand{\inner}[2]{\langle #1, #2 \rangle}\) \( \newcommand{\Span}{\mathrm{span}}\) \(\newcommand{\id}{\mathrm{id}}\) \( \newcommand{\Span}{\mathrm{span}}\) \( \newcommand{\kernel}{\mathrm{null}\,}\) \( \newcommand{\range}{\mathrm{range}\,}\) \( \newcommand{\RealPart}{\mathrm{Re}}\) \( \newcommand{\ImaginaryPart}{\mathrm{Im}}\) \( \newcommand{\Argument}{\mathrm{Arg}}\) \( \newcommand{\norm}[1]{\| #1 \|}\) \( \newcommand{\inner}[2]{\langle #1, #2 \rangle}\) \( \newcommand{\Span}{\mathrm{span}}\)\(\newcommand{\AA}{\unicode[.8,0]{x212B}}\)

    At the beginning of every function file, you should include a comment that explains what the function does:

    % res = myfunc(x)
    % Compute the Manhattan distance from the origin to the
    % point on the unit circle with angle (x) in radians.
    
    function res = myfunc(x)
    % this is not part of documentation given by help function
    
        s = sin(x);
        c = cos(x);
        res = abs(s) + abs(c);
    end

    When you ask for help, MATLAB prints the comment you provide.

    >> help myfunc
      res = myfunc(x)
      Compute the Manhattan distance from the origin to the
      point on the unit circle with angle (x) in radians.

    There are lots of conventions about what should be included in these comments. Among other things, it’s a good idea to include the following:

    Signature

    The signature of the function, which includes the name of the function, the input variable(s), and the output variable(s).

    Description

    A clear, concise, abstract description of what the function does. An abstract description is one that leaves out the details of how the function works and includes only information that someone using the function needs to know. You can put additional comments inside the function that explain the details.

    Variables

    An explanation of what the input variables mean; for example, in this case it is important to note that x is considered to be an angle in radians.

    Conditions

    Any preconditions and postconditions.


    This page titled 5.3: Function Documentation is shared under a CC BY-NC-SA 4.0 license and was authored, remixed, and/or curated by Allen B. Downey (Green Tea Press) via source content that was edited to the style and standards of the LibreTexts platform; a detailed edit history is available upon request.