MATLAB如何为程序或自定义函数添加帮助说明 | 为你的程序或自定义函数添加帮助说明

MATLAB如何添加帮助说明

在MATLAB里面，我们经常会自定义一些函数，而且通常会为这个函数写一段帮助说明文字来为我们或他人解释函数是做什么用以及怎么使用，每当我们在命令行（Command Window）里面输入help $SomeFuncion$ 时我们就会看到这段帮助说明文字（当然对于普通的.m程序文件也是同样可以如此操作，见为普通程序文件添加帮助说明。这篇博客会详细阐述如何去写一段说明帮助文字。

---

1. 创建MATLAB函数文件

我们可以直接创建一个后缀为.m的MATLAB脚本（Script）文件或者通过MATLAB新建一个函数（Function）文件，如下图，两个方式建立的文件格式是一样的，只不过用第二种方法创建的文件会自动生成一个模板（template），更加方便也更为推荐，我以这个方法为代表进行接下来的说明。

用新建一个函数的方式生成的MATLAB文件如下图这样，我这里不去赘述如何去写一个MATLAB函数，网络上有很多比较详细的教程，我只说如何写帮助说明。

2. 撰写帮助说明

当我们创建好了函数文件并且写好了函数内容以后我们就可以来写我们的帮助说明。

我们首先用pow2函数为例来说明一段详细的函数帮助说明会包含的内容。我们在命令行输入help pow2以后，MATLAB会返回如下图这样的内容，我们把这一大段内容可以分成三个部分（如下图1, 2, 3），接下来分别举例每个部分应该要写什么内容。

2.1 内容一：简要说明

第一部分通常只有一到两行，用来简略说明这个函数的作用，不必要包含如何使用。就像pow2里的pow2 Base 2 power and scale floating point number，而且这句话是顶格并且开头的pow2是被加粗的，这段话在MATLAB文件里面的应该是这样写的：

function ...
%POW2 Base 2 power and scale floating point number
...
end

没错，如果想要实现pow2被加粗的效果，需要全大写，即POW2.

2.2 内容二：使用方式和语法（syntax）

第二部分会比较详细，会有多行，是用来解释如何使用此函数，包括但不限于输入输出，比如我们输入pow2时的使用方式，或者叫语法（syntax）有X = pow2(Y)或者X = pow2(F,E)，并且详细解释了每一种语法的输入是对应做什么的。而且主要到这里的pow2还是被加粗了，同样，在MATLAB文件里面我需要全大写这部分，即

function ...
%POW2 Base 2 power and scale floating point number
%    X = POW2(Y) for each element of Y is 2 raised to the power Y.
% 
%    X = POW2(F,E) for each element of the real array F and a integer
%    array E computes X = F .* (2 .^ E).  The result is computed ...
...
end

注意这里如果需要表示一个空行，空行的前面也必须要用%开头。

2.3 内容三：扩展阅读

一般来说，一个函数文件只要前两个就可以了，但是有时这个函数会跟其他一些函数有一定关系，或者我们有更详细的帮助外部帮助文档，需要在帮助说明里面超链接展示出来。

如果是引用别的函数，可以直接大写这个函数的名字，只要你的另一个函数在同级文件夹下面或者已经提前加入了路径（类似环境变量，如何操作可看参考[2]，你就能通过大写这个函数的名字添加引用，用户点击这个超链接，就会自动出现对应的帮助说明。上面的See also log2, realmax, realmin.在MATLAB文件里面就是这样表示的：

...
%
%   See also LOG2, REALMAX, REALMIN.
...

如果需要表示一段链接着外部超链接的文字，则可以这样：

%   For more information, see <a href=
%   "https://blog.csdn.net/Undefinedefity">my CSDN blogs</a>.

效果如下

3. 为普通程序文件添加帮助说明

普通程序文件其实也是一样可以通过help $FileName$看帮助说明的，写作方法其实跟上面对函数的写作方法是一样的，比如这段命名为test.m的程序：

%TEST This is a sample test program to tell you how to write a help
%description
%   This paragrah should be the details of this matlab file
%   This paragrah should be the details of this matlab file
%   This paragrah should be the details of this matlab file
%   This paragrah should be the details of this matlab file
%
%   See also OTHERTEST.
%
%   For more information, see <a href=
%   "https://blog.csdn.net/Undefinedefity">my CSDN blogs</a>.

命令行输入help test：

4. 我的一个函数示例

这是我的一个MATLAB函数和其help说明，这个函数是用来生成旋转矩阵的：

function [R] = rot(axis, angle, homo)
%ROT   Returns a rotational matrix about a specific basic axis
%   R = ROT(axis, angle, 'homo')
%
%   axis = 'x', 'y', or 'z'.
%   angle should be in radian.
%   'homo' is optional if you want an homogenouse form else you do not need
%   to add it.
%
%   See also ROTX, ROTY, ROTZ, ROT2 of <a href=
%   "https://petercorke.com/toolboxes/robotics-toolbox/">The
%Robotics Toolbox for MATLAB (RTB) by Peter Corke</a>.

%   Version:            1.1
%   Author:             Def Li
%   Contact:            def460511281@163.com
%   last modified:      01/27/2021

ct = cos(angle);
st = sin(angle);

if nargin >3
    error('The number of input arguments should not be more than 3!');
    
elseif nargin == 3 && strcmp(homo, 'homo') % homogenouse form   
    if (axis == 'x')
        R = [
            1   0     0    0
            0   ct   -st   0
            0   st    ct   0
            0   0     0    1
            ];

    elseif (axis == 'y')
        R = [
             ct   0   st   0
             0    1   0    0
            -st   0   ct   0
             0    0   0    1
             ];
            

    elseif (axis == 'z')
        R = [
            ct   -st   0   0
            st    ct   0   0
            0     0    1   0
            0     0    0   1
            ];
    else
        error('Check your input!');
        
    end
    
elseif nargin ==2
    if (axis == 'x')
        R = [
            1   0     0
            0   ct   -st
            0   st    ct
            ];

    elseif (axis == 'y')
        R = [
             ct   0   st
             0    1   0 
            -st   0   ct
             ];
            

    elseif (axis == 'z')
        R = [
            ct   -st   0
            st    ct   0
            0     0    1
            ];
    else
        error('Check your input!');
        
    end
    
else
    error('Check your input!');

end

end

效果：

5. 参考

[1] MathWorks, Add Help for Your Program: https://www.mathworks.com/help/matlab/matlab_prog/add-help-for-your-program.html#d122e42128

[2] qnczmf, Matlab路径设置（3种方法）：https://blog.csdn.net/u012991043/article/details/84836971

[3] 桂哥317, 如何规范地编写一个MATLAB函数文件: https://blog.csdn.net/qq_15971883/article/details/82884353

返回顶部