2010-10-01 320 views
4

这个问题与我之前的问题有关:MATLAB m-file help formatting如何将作者身份和版本信息纳入MATLAB函数

你通常写什么来描述你自己的功能的作者身份?你是把它放在函数体的末尾,还是放在任何代码之前的帮助文本之后?

如何包含版本信息?功能修改后是否可以自动更新版本?

这就是我通常包括:

% My Name <[email protected]> 
% My company 
% Created: September 2010 
% Modified: October 2010 

请分享你的想法,想法?

回答

6

a function在MATLAB中央文件交换,可以帮助您记录在一个标准的方式你的函数,并与版本控制软件工程(CVS和Subversion;不GIT)自动更新的作者字段和时间修改。

您只需在命令提示符下键入new,然后输入函数的名称,然后对其余部分进行排序。

为我使用文档的基本模板是

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 

(你会明显地希望有一个不同的公司,你的版权声明。)

的帮助文档的第一行是被称为H1线,并由功能lookfor等使用。这很重要,它直接在函数定义行之后。

如果你有不同的用例(可能有和没有可选参数),那么你应该描述每个用例。

Examples:See also:行的格式与帮助报告生成器一起使用。 (我刚刚发现了一个bug - 年份应该在版权行中的公司名称前面),请修复此问题。

$Author:等格式化为与CSV/SVN一起使用。由于git使用文件散列,因此不能更改文件的内容,而不会考虑git已更新。

+0

哦,整合SVN整合工作(+1酷) !我不完全确定这些信息如何有用,只要我可以看看'svn log',但是我应该将它包含在我的函数模板中,以获得绝对的冷静。 $ author字段用修改函数的最后一个人更新,对吗? – Jonas 2010-10-01 20:40:59

+0

嗯,我是否需要更改SVN中的设置才能更新Author字段等? – Jonas 2010-10-01 20:54:41

+1

@Jonas:当您提交更改时,svn字段会更新,但您需要执行svn propset svn:keywords“Date Author Revision”filename.m'来配置它。请参阅http://svnbook.red-bean.com/en/1.4/svn.advanced.props.special.keywords.html。作者字段是当前用户的操作系统登录名。 – 2010-10-04 09:34:21

3

我们将代码保存在Subversion存储库中,并使用关键字功能将这类信息写入m文件的头部注释中,当它被提交到repo时。我们在大多数m文件的最初函数行之后放置了一段评论。

如果你不使用则源代码控制系统:

  1. 你真的应该开始使用一个现在。
  2. 您可以编写一个脚本(在Matlab中,为什么不),以维护您所需的注释信息,并实施一些过程以确保在必要时运行脚本。

我们通常不会在我们的源文件中放置修改日期或历史记录,存储库会跟踪我们的更改。这是你应该使用一个的另一个原因。

而且,当您正在考虑这一切时,如果您还没有这样做:请检查Matlab的publish功能。

编辑:@yuk:我想你从你提到的TortoiseSVN,你在Windows上工作。自从我在Windows PC上安装Subversion以来已有几年了。我完全没有记得安装过程中的任何问题,我也没有资格帮助您调试您的设备 - 但是有很多关于谁的问题。至于保持版本(等)信息是最新的,不需要脚本。您只需包含特殊字符串,例如$Rev$,Subversion将关键字识别为您需要版本信息(等)的文件位置(可能位于注释中)。这在Subversion Book中有很好的解释。

至于Matlab文档,我认为发布(及相关)功能在桌面工具和开发环境手册中有详细说明,该手册可在Mathworks网站上在线获得。

+1

+1同意源代码管理和使用关键字。我们尝试在类级别定义所有权,并将“作者”信息仅放置在用于构造函数文件的帮助文本中。我们把它放在帮助文本中,而不是结束,因此联系信息显示在“帮助”输出中。因为M代码创建了大量文件 - 每个函数1个而不是每个类或Java或C模块1个 - 每个文件中的标题信息看起来都很混乱。我们不希望它为每一个“帮助”调用消耗屏幕空间。 – 2010-10-01 16:37:56

+0

谢谢,马克。我明白我必须使用版本控制。我其实尝试设置TortoiseSVN,但在安装服务器时遇到了一些问题。不记得细节,这是前一阵子。你有链接到一些教程?你能否添加一些关于如何在MATLAB中编写和设置脚本版本信息更新的更多细节?至于发布,我当然看了看,但找不到相关信息。 – yuk 2010-10-01 16:49:31

+0

+1使用源代码管理,它实际上是必须的!最新一代是HG(Mercurial)和Git,请参阅:http://stackoverflow.com/questions/3183064/git-vs-mercurial-vs-svn-closed – Mikhail 2010-10-02 11:00:47

1

正如High Performance Mark指出的那样,某种形式的源代码控制对于处理这种情况是理想的。但是,如果要添加手工信息这里有几个要点:

  • 我肯定会包括一行陈述MATLAB版本的代码写在,或者你知道哪个版本,它为。

  • 当添加的信息,你必须把它和帮助注释块之间留出空间,如果您想要显示它当用户查看help contents,像这样:

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

    除非你希望它显示的帮助。然后制作一个大的评论块。