views:

68

answers:

3

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?

+3  A: 

We keep our code in a Subversion repository and use the keywords functionality for writing this sort of information into the header comments of the m-file when it is committed to the repo. We put a block of comments right after the initial function line in (most of) our m-files.

If you are not using a source code control system then:

  1. You really should start using one right now.
  2. You could write a script (in Matlab, why not) for maintaining the comment information you require, and implement some process to ensure that you run the script when necessary.

We don't generally put modification dates or histories in our source files, the repository tracks changes for us. Which is another reason you should be using one.

And, while you are thinking about all this, if you haven't already done so: check out Matlab's publish functionality.

EDIT: @yuk: I guess from your mention of TortoiseSVN that you are working on Windows. It's a couple of years since I installed Subversion on my Windows PC. I don't recall any problems at all with the installation, and I'm not qualified to help you debug yours -- but there are plenty on SO who are.

As for keeping version (etc) info up to date, there's no scripting required. You simply include the special strings, such as $Rev$, which Subversion recognises as keywords in the locations in your files (probably in the comments) where you want the version information (etc). This is well explained in the Subversion Book.

As for the Matlab documentation, I think the publish (and related) features are well explained in the Desktop Tools and Development Environment handbook which is available on-line at the Mathworks web-site.

High Performance Mark
+1 Agreed on source control and using keywords. We try to define ownership at the class level, and put the "author" info in the helptext for constructor files only. We put it in helptext instead of at end so the contact info shows up in the "help" output. Because M-code creates a lot of files - 1 per function instead of 1 per class or module like Java or C - having header info in every file seems cluttery. And we don't want it consuming screen space for every single "help" call.
Andrew Janke
Thanks, Mark. I understand I have to use version control. I actually tried setting up TortoiseSVN, but had some problems installing the server. Don't remember details, it was awhile ago. Do you have a link to some tutorial? Would you please add some more details on how to write and setup a script in MATLAB for version info update? As for publish, I looked at it, of course, but could not find relevant information.
yuk
+1 for using source control, it is actually a must! The newest generation is HG (Mercurial) and Git, see: http://stackoverflow.com/questions/3183064/git-vs-mercurial-vs-svn-closed
Mikhail
+1  A: 

As High Performance Mark points out, some form of source code control is ideal for handling this situation. However, if you are adding information by hand here are a few pointers:

  • I would definitely include a line stating the MATLAB version your code was written in, or perhaps which versions you know it works for.

  • When adding the information, you have to leave space between it and the help comment block if you don't want to display it when the user views the help contents, like so:

    function myFunction
    %# Help text for function
    
    
    %# Your information
    

    Unless you do want it displayed with the help. Then just make one big comment block.

gnovice
+3  A: 

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.

Richie Cotton
Oh, neat work on the SVN integration (+1 cool)! I'm not entirely sure how this information will be useful as long as I can have a look at `svn log`, but I should include it in my function template for sheer coolness. The $author field is updated with the last person who revised the function, right?
Jonas
Hm, do I need to change a setting in SVN in order for the Author fields etc to update?
Jonas
@Jonas: The svn fields update when you commit you changes but you need to do `svn propset svn:keywords "Date Author Revision" filename.m` to configure it. See http://svnbook.red-bean.com/en/1.4/svn.advanced.props.special.keywords.html. The Author field is the OS login name of the current user.
Richie Cotton
@Richie Cotton: Thanks a lot for your help!
Jonas