我有一个函数 在 MATLAB Central File Exchange 中，可帮助您以标准方式记录函数，并与版本控制软件（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: 行的格式与帮助报告生成器配合使用。 （我刚刚发现了一个错误 - 版权行中的年份应该位于公司名称之前。正在修复中。）
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.
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:
You really should start using one right now.
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.
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.
发布评论
评论（3）
我有一个函数 在 MATLAB Central File Exchange 中，可帮助您以标准方式记录函数，并与版本控制软件（CVS 和 Subversion；不是 git）配合使用，自动更新作者字段和修改时间。
您只需在命令提示符处输入 new，然后输入函数名称，它就会处理其余的事情。
我使用的文档的基本模板是
（您显然希望在版权声明中使用不同的公司。）
帮助文档的第一行称为 H1 行，由函数
lookfor等等。重要的是它紧接在函数定义行之后。如果您有不同的用例（可能有或没有可选参数），那么您应该描述每一个。
Examples:和See Also:行的格式与帮助报告生成器配合使用。 （我刚刚发现了一个错误 - 版权行中的年份应该位于公司名称之前。正在修复中。）$Author:等已格式化为与 CSV/SVN 一起使用。由于 git 使用文件的哈希值，因此您无法更改文件的内容，除非 git 认为文件已更新。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
newat the command prompt, then the name of the function, and it sorts out the rest.The basic template for documentation that I use is
(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:andSee 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.我们将代码保存在 Subversion 存储库中，并在提交到存储库时使用关键字功能将此类信息写入 m 文件的标头注释中。我们在（大多数）m 文件中的初始函数行之后放置了一块注释。
如果您没有使用源代码控制系统，那么：
我们通常不会将修改日期或历史记录放入源文件中，存储库会为我们跟踪更改。这是您应该使用它的另一个原因。
而且，当您考虑所有这些时，如果您还没有这样做：请查看 Matlab 的
publish功能。编辑：@yuk：从你提到的 TortoiseSVN 中我猜你正在 Windows 上工作。我在 Windows PC 上安装 Subversion 已经有几年了。我不记得安装有任何问题，而且我没有资格帮助你调试你的——但是有很多这样的人。
至于保持版本（等）信息最新，不需要编写脚本。您只需将特殊字符串（例如
$Rev$）包含在文件中您想要版本信息的位置（可能在注释中），Subversion 将其识别为关键字 （ETC）。 Subversion Book 对此进行了很好的解释。至于 Matlab 文档，我认为发布（及相关）功能在《桌面工具和开发环境》手册中得到了很好的解释，该手册可在 Mathworks 网站上在线获取。
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:
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
publishfunctionality.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.
作为高性能标记 指出，某种形式的源代码控制是处理这种情况的理想选择。但是，如果您要手动添加信息，这里有一些提示：
我肯定会包含一行，说明您编写的代码所用的 MATLAB 版本，或者您知道它适用于哪些版本。
添加信息时，如果您不想在用户查看帮助内容，如下所示：
除非您确实希望它与帮助一起显示。然后就制作一个大的注释块。
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:
Unless you do want it displayed with the help. Then just make one big comment block.