How do you include authorship and version info into your MATLAB functions [closed]

Question

This question is related to my previous one: MATLAB m-file help formatting.

What do you usually write to describe authorship of your own function? Do you put it at the end of the function body or right after the help text before any code?

How do you include version information? Is it possible to automatically update version after function modification?

This is what I usually include:

% My Name <my@email>
% My company
% Created: September 2010
% Modified: October 2010

Please share your thoughts, ideas?

Answer 1

I have a function in the MATLAB Central File Exchange that helps you document your function in a standard way, and works with version control software (CVS and Subversion; not git) to automatically update the author field and time of modification.

You just type new at the command prompt, then the name of the function, and it sorts out the rest.

The basic template for documentation that I use is

function [outputArgs] = TestFunction(inputArgs)
%TESTFUNCTION Summary of this function goes here
% 
% [OUTPUTARGS] = TESTFUNCTION(INPUTARGS) Explain usage here
% 
% Examples: 
% 
% Provide sample usage code here
% 
% See also: List related files here

% $Author: rcotton $    $Date: 2010/10/01 18:23:52 $    $Revision: 0.1 $
% Copyright: Health and Safety Laboratory 2010

(You'll obviously want a different company in your copyright statement.)

The first line of the help documentation is known as the H1 line, and is used by the function lookfor, among others. It is important that this comes straight after the function definition line.

If you have different use cases (maybe with and without optional arguments), then you should describe each one.

The Examples: and See also: lines are formatted in a way the works with the help report generator. (I've just spotted a bug - the year should be before the company name in the copyright line. Fix on its way.)

$Author:, etc., are formatted for use with CSV/SVN. Since git uses hashes of files, you can't change the content of the file, without git thinking that it's been updated.