-------------------------------------------------------------------------------
MATLAB's Help on Functions
copied directly from Help Browser and command-window help
-------------------------------------------------------------------------------
Getting Started: Programming with MATLAB: Functions

Functions are M-files that can accept input arguments and return
output arguments. The name of the M-file and of the function should be
the same. Functions operate on variables within their own workspace,
separate from the workspace you access at the MATLAB command prompt.

A good example is provided by rank. The M-file rank.m is available in
the directory

toolbox/matlab/matfun
You can see the file with

type rank
Here is the file.

function r = rank(A,tol)
%   RANK Matrix rank.
%   RANK(A) provides an estimate of the number of linearly
%   independent rows or columns of a matrix A.
%   RANK(A,tol) is the number of singular values of A
%   that are larger than tol.
%   RANK(A) uses the default tol = max(size(A)) * norm(A) * eps.
s = svd(A);
if nargin==1
   tol = max(size(A)') * max(s) * eps;
end
r = sum(s > tol);
The first line of a function M-file starts with the keyword
function. It gives the function name and order of arguments. In this
case, there are up to two input arguments and one output argument. 

The next several lines, up to the first blank or executable line, are
comment lines that provide the help text. These lines are printed when
you type

help rank

The first line of the help text is the H1 line, which MATLAB displays
when you use the lookfor command or request help on a directory.

The rest of the file is the executable MATLAB code defining the
function. The variable s introduced in the body of the function, as
well as the variables on the first line, r, A and tol, are all local
to the function; they are separate from any variables in the MATLAB
workspace.

This example illustrates one aspect of MATLAB functions that is not
ordinarily found in other programming languages - a variable number of
arguments. The rank function can be used in several different ways.

rank(A)
r = rank(A)
r = rank(A,1.e-6)
Many M-files work this way. If no output argument is supplied, the
result is stored in ans. If the second input argument is not supplied,
the function computes a default value. Within the body of the
function, two quantities named nargin and nargout are available which
tell you the number of input and output arguments involved in each
particular use of the function. The rank function uses nargin, but
does not need to use nargout.
-------------------------------------------------------------------------------
MATLAB Function Reference: function

Description
You add new functions to MATLAB's vocabulary by expressing them in
terms of existing functions. The existing commands and functions that
compose the new function reside in a text file called an
M-file. M-files can be either scripts or functions. Scripts are simply
files containing a sequence of MATLAB statements. Functions make use
of their own local variables and accept input arguments.

The name of an M-file begins with an alphabetic character, and has a
filename extension of .m . The M-file name, less its extension, is
what MATLAB searches for when you try to use the script or function.

A line at the top of a function M-file contains the syntax
definition. The name of a function, as defined in the first line of
the M-file, should be the same as the name of the file without the .m
extension. For example, the existence of a file on disk called stat.m with

function [mean,stdev] = stat(x)
n = length(x);
mean = sum(x)/n;
stdev = sqrt(sum((x-mean).^2/n));

defines a new function called stat that calculates the mean and
standard deviation of a vector. The variables within the body of the
function are all local variables.

A subfunction,visible only to the other functions in the same file, is
created by defining a new function with the function keyword after the
body of the preceding function or subfunction. For example, avg is a
subfunction within the file stat.m:

function [mean,stdev] = stat(x)
n = length(x);
mean = avg(x,n);
stdev = sqrt(sum((x-avg(x,n)).^2)/n);
function mean = avg(x,n)
mean = sum(x)/n;

Subfunctions are not visible outside the file where they are
defined. Functions normally return when the end of the function is
reached. Use a return statement to force an early return.

When MATLAB does not recognize a function by name, it searches for a
file of the same name on disk. If the function is found, MATLAB
compiles it into memory for subsequent use. In general, if you input
the name of something to MATLAB, the MATLAB interpreter:

1. Checks to see if the name is a variable.
2. Checks to see if the name is an internal function (eig, sin) that was
   not overloaded.
3. Checks to see if the name is a local function (local in sense of
   multifunction file).
4. Checks to see if the name is a function in a private directory.
5. Locates any and all occurrences of function in method directories and
   on the path. Order is of no importance.

At execution, MATLAB:

1. Checks to see if the name is wired to a specific function (2, 3, & 4 above)
2. Uses precedence rules to determine which instance from 5 above to call
   (we may default to an internal MATLAB function).

Constructors have higher precedence than anything else.

When you call an M-file function from the command line or from within
another M-file, MATLAB parses the function and stores it in
memory. The parsed function remains in memory until cleared with the
clear command or you quit MATLAB. The pcode command performs the
parsing step and stores the result on the disk as a P-file to be
loaded later.

See Also
nargin, nargout, pcode, varargin, varargout, what
-------------------------------------------------------------------------------
Programming and Data Types: M-File Programming: Functions

Functions are M-files that accept input arguments and return output
arguments. They operate on variables within their own workspace. This
is separate from the workspace you access at the MATLAB command
prompt.

This section covers the following topics regarding functions:

Simple Script Example
Basic Parts of a Function M-File
Function Names
How Functions Work
Checking the Number of Function Arguments
Passing Variable Numbers of Arguments

(each of these has extensive notes!)
-------------------------------------------------------------------------------
From >> help function

 FUNCTION Add new function.
    New functions may be added to MATLAB's vocabulary if they
    are expressed in terms of other existing functions. The 
    commands and functions that comprise the new function must
    be put in a file whose name defines the name of the new 
    function, with a filename extension of '.m'. At the top of
    the file must be a line that contains the syntax definition
    for the new function. For example, the existence of a file 
    on disk called STAT.M with:
  
            function [mean,stdev] = stat(x)
            %STAT Interesting statistics.
            n = length(x);
            mean = sum(x) / n;
            stdev = sqrt(sum((x - mean).^2)/n);
  
    defines a new function called STAT that calculates the 
    mean and standard deviation of a vector. The variables
    within the body of the function are all local variables.
    See SCRIPT for procedures that work globally on the work-
    space. 
 
    A subfunction that is visible to the other functions in the
    same file is created by defining a new function with the FUNCTION
    keyword after the body of the preceding function or subfunction.
    For example, avg is a subfunction within the file STAT.M:
 
           function [mean,stdev] = stat(x)
           %STAT Interesting statistics.
           n = length(x);
           mean = avg(x,n);
           stdev = sqrt(sum((x-avg(x,n)).^2)/n);
 
           %-------------------------
           function mean = avg(x,n)
           %MEAN subfunction
           mean = sum(x)/n;
 
    Subfunctions are not visible outside the file where they are defined.
    Normally functions return when the end of the function is reached.
    A RETURN statement can be used to force an early return.
 
    See also SCRIPT, RETURN, VARARGIN, VARARGOUT, NARGIN, NARGOUT, 
             INPUTNAME, MFILENAME.
-------------------------------------------------------------------------------