Question

这个问题与我之前的问题有关：MATLAB m-file help formatting。

你通常用什么来描述自己职能的作者？您是将它放在功能体的末尾还是在任何代码之前的帮助文本之后？

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

这是我通常包括的内容：

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

请分享您的想法，想法？

Answer 1

我在MATLAB中央文件交换中有a function帮助您以标准方式记录您的功能，并使用版本控制软件（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:行的格式与帮助报告生成器的工作方式相同。（我刚刚发现了一个错误 - 这一年应该在版权行中的公司名称之前。修复它。）

$Author:等格式化为与CSV / SVN一起使用。由于git使用文件的哈希值，因此您无法更改文件的内容，而git不会认为它已被更新。

Answer 2

我们将代码保存在Subversion存储库中，并使用关键字功能将此类信息写入m文件的标题注释中，并将其提交到repo。我们在（大部分）m文件中的初始函数行之后放置了一个注释块。

如果您没有使用源代码控制系统，那么：

你现在真的应该开始使用。
您可以编写一个脚本（在Matlab中，为什么不这样做）来维护您需要的注释信息，并实现一些过程以确保您在必要时运行脚本。

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

而且，当您考虑所有这些时，如果您还没有这样做：查看Matlab的publish功能。

至于保持版本（等）信息是最新的，不需要脚本。您只需在文件中的位置（可能在注释中）中包含特殊字符串，例如 $Rev$ ，其中Subversion将其识别为 keywords ，您可以在其中获取版本信息（等）。这在Subversion Book。

至于Matlab文档，我认为发布（和相关）功能在桌面工具和开发环境手册中得到了很好的解释，该手册可在Mathworks网站上在线获取。< / p>

Answer 3

正如High Performance Mark所指出的，某种形式的源代码控制是处理这种情况的理想选择。但是，如果您手动添加信息，请参阅以下几点：

我肯定会在一行中说明您编写代码的MATLAB版本，或者您知道它适用于哪种版本。
添加信息时，如果不想要在用户查看help contents时显示该信息，则必须在其与帮助注释块之间留出空格，像这样：
```
function myFunction
%# Help text for function

%# Your information
```
除非你做希望在帮助下显示它。然后只做一个大评论块。

如何将作者和版本信息包含在MATLAB函数中

3 个答案: