这篇笔记只为了解决两个问题：如何基于命令行使用MATLAB的帮助文档系统？如何让自己编写的代码（函数和类）适配MATLAB的帮助系统？

获取帮助

doc & docsearch

打开 MATLAB 文档浏览器（最新版已经改成使用系统浏览器），显示帮助中心对应的完整页面。

打开帮助中心首页 

1
doc

打开abs对应的页面 

1
doc abs

在帮助中心搜索关键字 

1
docsearch abs

这两个命令都是完全基于离线版的MATLAB帮助中心，和在线的MATLAB帮助中心几乎一致（除了版本和语言可能不同），通常不支持对用户自定义代码的帮助。

help

help 命令可以在命令行中显示简要帮助信息。

  • help name 会显示 name 指定的功能的帮助文本，例如函数、方法、类、工具箱、变量或命名空间。
  • help 则会显示与先前操作相关的内容。

例如查找函数的帮助信息 

1
help abs

输出内容如下 

1
2
3
4
5
6
7
8
9
abs    Absolute value.
   abs(X) is the absolute value of the elements of X. When
   X is complex, abs(X) is the complex modulus (magnitude) of
   the elements of X.

   See also sign, angle, unwrap, hypot.

   Documentation for abs
   Other uses of abs

对于不同的 name，help 的处理逻辑略有不同，具体来说：

  • 如果 name 是变量，help 显示该变量的类的帮助文本。
  • 要获取某个类的方法/属性的帮助，可以指定类名和方法名称（以句点分隔）。例如，要获取 classname 类的 methodname 方法的帮助，请键入 help classname.methodname。
  • 如果 name 出现在 MATLAB 搜索路径上的多个文件夹中，help 将显示在搜索路径中找到的 name 的第一个实例的帮助文本。
  • 如果 name 指定文件夹的名称或部分路径，help 函数默认将列出文件夹中每个程序文件的帮助文本的第一行。如果文件夹中含有特殊的 Contents.m 文件（通常包括这个文件夹中的内容说明），会影响这里的行为。

lookfor

lookfor 会在 MATLAB 文档中所有参考页的摘要行和函数名称以及第三方和用户编写的 MATLAB 程序文件的帮助文本中搜索指定的关键字。

搜索可能比较耗时，搜索常用词得到的匹配结果通常有很多，最终会在命令行中以列表形式展示所有结果，每一行是对应的条目（指向的链接）以及对应的帮助文本的第一行（也就是使用 help 命令所展示的第一行内容）。 点击提供的链接相当于使用 help 命令查看对应条目，会在命令行中显示这一项的完整帮助信息。

例如 

1
lookfor legendre

输出内容如下 

1
2
legendre                       - Associated Legendre functions
sym.legendreP                  - Legendre polynomials

如果将自己编写的相关代码也添加到 MATLAB 的搜索路径中，那么 lookfor 命令也会显示自己编写的代码，例如 

1
2
3
4
5
6
7
legendre                       - Associated Legendre functions
sym.legendreP                  - Legendre polynomials
gauss_legendre                 - Computation of the Nodes and Weights for the Gauss-Legendre Quadrature.
MatLegendre                    - : A class that provides Legendre polynomial basis functions.
MatLegendreDx                  - : A class that provides Legendre polynomial derivatives.
test_MatLegendre               - Test suite for MatLegendre class
test_MatLegendreDx             - Test suite for MatLegendreDx class

适配帮助系统

现在我们关注如何让自己的代码尽可以符合MATLAB的规范，从而适配MATLAB的帮助系统。

虽然语言的定位类似，但是相比于Python可以使用注解进行类型提示，并结合代码分析工具进行静态检查，MATLAB其实更需要通过注释提供信息，因为有时传入的参数是列向量还是行向量都可能导致结果的差异。

给函数文件添加注释

MATLAB的帮助命令将函数文件从文件开头找到的一大段注释视作帮助信息，帮助信息的第一行视作摘要。 建议在帮助信息中包括函数名称、简要说明、参数说明、返回值说明、示例代码等，在第一行的摘要中包括函数名称和简要说明。

注释通常会写在函数定义之后紧接的行，例如下面是官方文档提供的函数注释示例 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
function c = addme(a,b)
    % ADDME  Add two values together.
    %   C = ADDME(A) adds A to itself.
    %
    %   C = ADDME(A,B) adds A and B together.
    %
    %   See also SUM, PLUS.

    switch nargin
        case 2
            c = a + b;
        case 1
            c = a + a;
        otherwise
            c = 0;
end

但是并不必要，例如下面这两种写法都是可以的 

1
2
3
4
5
6
function func1()

    % xxxxxxxxxxx

    disp('hi')
end

1
2
help func1
  xxxxxxxxxxx
1
2
3
4
5
6
% xxxxxxxxxxx
function func2()
    % yyyyyyyyyyyy

    disp('hi')
end
1
2
help func2
  xxxxxxxxxxx

放置在代码之后的注释则不会被视作帮助信息，此时只会显示默认信息 

1
2
3
4
5
function func3()

    disp('hi')
    % xxxxxxxxxxx
end

1
2
help func3
func is a function.

在帮助信息的最后一行支持如下写法 

1
%   See also SUM, PLUS.

此时MATLAB会尝试将SUM和PLUS链接到对应的帮助信息，否则会原样显示。

给类文件添加注释

类文件的帮助信息与函数文件基本类似，参考写法如下 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
classdef myClass
    % myClass   Summary of myClass
    % This is the first line of the description of myClass.
    % Descriptions can include multiple lines of text.
    %
    % myClass Properties:
    %    a - Description of a
    %    b - Description of b
    %
    % myClass Methods:
    %    doThis - Description of doThis
    %    doThat - Description of doThat

    properties
        a          % First property of myClass

        % b - Second property of myClass
        % The description for b has several
        % lines of text.
        b          % Other comment
    end

    methods
        function obj = myClass
        end

        function doThis(obj)
            % doThis  Do this thing
            %   Here is some help text for the doThis method.
            %
            %   See also DOTHAT.

            disp(obj)
        end
        function doThat(obj)
            % doThat  Do that thing
            %   Here is some help text for the doThat method.
            %
            %   See also DOTHIS.

            disp(obj)
        end
    end

end

下面对第一段帮助信息的各个部分进行解释：

  • 首先是类的名称以及一行摘要；
  • 然后是类的简要描述语句；
  • 最后是属性列表和说明，以及方法列表和说明，如果其中包含类名称且后跟 Properties 或 Methods 以及一个冒号 (:)，MATLAB 将创建指向这些属性或方法的帮助的超链接。

在属性列表中，可以在属性后面（或者上面）加上注释，这样就可以支持 help 命令对该属性获取帮助信息，例如 

1
2
help myClass.a
 a -  First property of myClass

在方法列表中，可以在方法内部加上注释，与函数注释基本相同，这样就可以支持 help 命令对该方法获取帮助信息，例如 

1
2
3
4
5
help myClass.doThis
  doThis  Do this thing
    Here is some help text for the doThis method.

    See also doThat.

注意：这里在类的帮助信息中展示的属性和方法最好是public的，私有的属性和方法可能无法在帮助信息中自动创建对应的链接。