自定义代码建议和自动填充

要为您的函数和类自定义代码建议和自动填充，请向 MATLAB^® 提供有关您的函数签名的信息。函数签名说明函数可接受的语法和允许的数据类型。MATLAB 使用此信息在编辑器、实时编辑器和命令行窗口中显示代码建议和自动填充。在名为 functionSignatures.json 的 JSON 格式文件中定义该函数信息。

要使 MATLAB 检测函数签名信息，您必须将 functionSignatures.json 放入包含函数代码的文件夹中。如果为类方法或包函数定义信息，必须将 functionSignatures.json 放在最外层类或包文件夹的父文件夹中。例如，要为 myClass 的方法定义信息，请将 functionSignatures.json 放在这些类和包结构体的 myFolder 文件夹中：

  myFolder/+myPackage/@myClass
  myFolder/+myPackage/+mySubpackage/@myClass

对于位于类文件夹或包文件夹之外的类，请将 functionSignatures.json 放在包含类代码的文件夹中。您可以在同一个文件中为多个函数定义签名。

functionSignatures.json 文件只包含一个 JSON 对象。JSON 使用花括号来定义对象，并以名称-值对组集合的形式引用对象。由于这些术语在函数签名的语境下使用过多，因而此处使用“属性”而非“名称”。functionSignatures.json 中的 JSON 对象包含架构版本（可选）和函数对象列表。每个函数对象都包含一个签名对象列表，每个签名对象包含一个参数对象数组。JSON 使用方括号来定义数组。

要指定架构版本（可选），请使用 _schemaVersion 作为第一个属性，使用版本号作为其值。将版本号指定为 major#.minor#.patch# 格式的 JSON 字符串，其中每个数字指定为非负整数。当前架构版本是 1.0.0。如果文件未指定架构版本，则 MATLAB 假定版本为 1.0.0。

如果 functionSignatures.json 包含语法错误，MATLAB 在读取文件时会在命令行窗口中显示错误消息。使用 validateFunctionSignaturesJSON 函数根据 JSON 架构和 MATLAB 函数签名架构验证 functionSignatures.json 文件。

函数对象

要为函数定义信息，请创建一个与函数名称相同的属性。它的值是签名对象。

{
  "functionName1": { signatureObj1 },
  "functionName2": { signatureObj2 }
}

要为类构造函数、类方法或包函数定义信息，请使用函数或方法的全名。例如，定义类构造函数、类方法 myMethod 和包函数 myFunction。

{
  "myClass.myClass": { signatureObj },
  "myClass.myMethod": { signatureObj },
  "myPackage.myFunction": { signatureObj }
}

通过定义具有相同属性（函数或方法名称）的多个函数对象，可以为同一个函数或方法定义多个函数签名。有关详细信息，请参阅多个签名。

签名对象

签名对象定义函数的输入和输出参数以及支持的平台。每个属性的值（platforms 属性除外）都是一个参数对象数组。

{
  "functionName1":
  {
     "inputs": [ argumentObj1, argumentObj2 ]
  }
}

如果在 JSON 文件中指定实例方法，如 myClass.myMethod，则 inputs 中的元素之一必须为 myClass 的对象。通常，此对象是第一个元素。当您使用圆点表示法 (b = myObj.myMethod(a)) 或函数表示法 (b = myMethod(myObj,a)) 语法调用指定方法时，MATLAB 支持针对该方法的代码建议和自动填充。

JSON 文件中的每个签名都可以包括以下属性。

属性描述值的 JSON 数据类型

属性	描述	值的 JSON 数据类型
`inputs`	函数输入参数的列表。MATLAB 将此属性用于代码建议和自动填充。	参数对象数组
`outputs`	函数输出参数列表。MATLAB 使用此属性来优化代码建议和自动填充。	参数对象数组
`platforms`	支持该函数的平台的列表。如果平台不支持该函数，MATLAB 不会显示自定义代码建议和自动填充。默认是所有平台。列表的元素必须与 `computer` 函数返回的 `archstr` 匹配。该列表要么列出所有支持的平台，要么列出所有不支持的平台，但不能同时列出支持和不支持的平台。示例值为 `"win64,maci64"` 或 `"-win64,-maci64"`。	逗号分隔值的字符串

inputs

函数输入参数的列表。MATLAB 将此属性用于代码建议和自动填充。

参数对象数组

outputs

函数输出参数列表。MATLAB 使用此属性来优化代码建议和自动填充。

参数对象数组

platforms

支持该函数的平台的列表。如果平台不支持该函数，MATLAB 不会显示自定义代码建议和自动填充。

默认是所有平台。列表的元素必须与 computer 函数返回的 archstr 匹配。该列表要么列出所有支持的平台，要么列出所有不支持的平台，但不能同时列出支持和不支持的平台。示例值为 "win64,maci64" 或 "-win64,-maci64"。

逗号分隔值的字符串

参数对象

参数对象定义每个输入和输出参数的信息。

{
  "functionName1":
  {
     "inputs":
     [
        {"name":"in1",  "kind":"required", "type":["numeric"]},
        {"name":"in2",  "kind":"required", "type":["numeric","integer","scalar"]}
     ]
  }
}

各个输入在 JSON 文件中的显示顺序非常重要。例如，在对 functionName1 函数的调用中，in1 必须出现在 in2 之前。

每个参数对象可以包含以下属性。

name - 参数的名称

kind - 参数的种类

值	描述
`required`	参数是必需的，其位置相对于签名对象中的其他必需参数。
`ordered`	参数是可选的，其位置相对于签名对象中的必需参数和前面的可选参数。
`namevalue`	参数是可选的名称-值对组。名称-值对组参数出现在函数签名的末尾，但这些对组可以按任意顺序指定。

type - 参数的类和/或属性

参数的类或属性，指定为 JSON 字符串、列表或者列表的列表。

type 属性可以定义参数是哪个类以及参数必须具有哪些属性。

要匹配一个类或属性，请使用单个 JSON 字符串。例如，如果参数必须是数值，则指定 "type":"numeric"。
要匹配所有类或属性，请使用 JSON 字符串列表。例如，如果某个参数必须既是数值又是正数，则指定 "type":["numeric", ">=0"]。
要匹配多个类或属性中的任意多个，请使用 JSON 字符串列表的列表。在内层列表，MATLAB 对各值执行逻辑 AND 运算。在外层列表，MATLAB 对各值执行逻辑 OR 运算。例如，如果参数必须要么是正数，要么是 containers.Map 对象，则指定 "type":[["numeric", ">=0"],["containers.Map"]]。

值	参数描述
`"classname"`	必须是类 classname 的对象，其中 classname 是 `class` 函数返回的类的名称。例如，`"double"` 或 `"function_handle"`。
`"choices=expression"`	必须是指定选项之一的匹配项（不区分大小写）。expression 是返回字符向量元胞、字符串数组或整数值元胞的有效 MATLAB 表达式。例如，`"choices={'on','off'}"` 或 `"choices={8, 16, 24}"`。 expression 可以按名称引用出现在参数列表中的其他输入参数。由于 expression 是在运行时计算的，因此允许的选项可以随其他输入参数的值动态变化。
`"file=*.ext,..."`	必须是字符串或字符向量，表示具有指定扩展名的现有文件的名称。文件名相对于当前工作文件夹。例如，要允许当前文件夹中的所有 `.m` 和 `.mlx` 文件，请使用 `"file=.m,.mlx"`。要匹配当前文件夹中的所有文件，请使用 `"file"`。
`"folder"`	必须是相对于当前工作文件夹的某一现有文件夹的名称的字符串或字符向量。
`"matlabpathfile=*.ext,..."`	必须是指名 MATLAB 路径上某一现有文件的字符串或字符向量。该值至少需要一个文件扩展名。例如，要允许路径中的所有 `.mat` 文件，请使用 `"matlabpathfile=*.mat"`。
`"size=size1,size2,…,sizeN"`	必须符合大小限制。该值要求至少两个维度。每个大小维度只能是正整数（指示允许的维度大小）或冒号（表示允许任何大小）。例如，`"size=2,:,2"` 约束参数在第 1 个和第 3 个维度中的大小为 2。
`"numel=integerValue"`	必须有指定数量的元素。
`"nrows=integerValue"`	必须有指定数量的行。
`"ncols=integerValue"`	必须有指定数量的列。
`"numeric"`	必须是数值。数值型的值是用 `isa` 函数判断其是否属于 `'numeric'` 类时返回 `true` 的值。
`"logical"`	必须是数值或逻辑值。
`"real"`	必须是实数值或字符或逻辑值。
`"scalar"`	必须是标量。
`"integer"`	必须是 `double` 类型的整数。
`"square"`	必须是方阵。
`"vector"`	必须是列或行向量。
`"column"`	必须是列向量。
`"row"`	必须是行向量。
`"2d"`	必须是二维的。
`"3d"`	不得超过三个维度。
`"sparse"`	必须是稀疏类型。
`"positive"`	必须大于零。
`">expression"`	必须是数值且满足不等式。expression 必须返回全双精度标量。
`">=expression"`
`"<expression"`
`"<=expression"`
`@(args) expression`	必须满足函数句柄。要使值满足函数句柄，句柄的计算结果必须为 `true`。

repeating - 多次指定参数

purpose - 参数描述

对于更复杂的函数签名，各个参数对象均可使用以下属性。

platforms - 支持的平台的列表

tuple - 参数集的定义

mutuallyExclusiveGroup - 互斥参数集的定义

创建函数签名文件

此示例说明如何为函数创建自定义代码建议和自动填充。

创建一个函数，其签名将在后续步骤中由 JSON 文件加以描述。以下函数接受：

两个必需参数
一个可选的位置参数（通过 varargin）
两个可选的名称-值对组参数（通过 varargin）

此处使用 myFunc 来演示代码建议，其中不包含参数检查。

% myFunc  Example function
% This function is called with any of these syntaxes:
%
%   myFunc(in1, in2) accepts 2 required arguments. 
%   myFunc(in1, in2, in3) also accepts an optional 3rd argument. 
%   myFunc(___, NAME, VALUE) accepts one or more of the following name-value pair 
%       arguments. This syntax can be used in any of the previous syntaxes.
%           * 'NAME1' with logical value
%           * 'NAME2' with 'Default', 'Choice1', or 'Choice2'
function myFunc(reqA,reqB,varargin)
    % Initialize default values
    NV1 = true;
    NV2 = 'Default';
    posA = [];
    
    if nargin > 3
        if rem(nargin,2)
            posA = varargin{1};
            V = varargin(2:end);
        else
            V = varargin;
        end
        for n = 1:2:size(V,2)
            switch V{n}
                case 'Name1'
                    NV1 = V{n+1};
                case 'Name2'
                    NV2 = V{n+1}
                otherwise
                    error('Error.')
            end
        end
    end
end

在 myFunc 所在的文件夹中，在名为 functionSignatures.json 的文件中创建以下函数签名描述。输入名称与 myFunc 主体中的名称不匹配，但与帮助文本一致。

{
  "_schemaVersion": "1.0.0",
  "myFunc":
  {
     "inputs":
     [
        {"name":"in1", "kind":"required", "type":["numeric"], "purpose":"ID of item"},
        {"name":"in2", "kind":"required", "type":["numeric"], "purpose":"# Items"},
        {"name":"in3", "kind":"ordered", "type":["numeric"], "purpose":"Input Value"},
        {"name":"Name1", "kind":"namevalue", "type":["logical","scalar"],"purpose":"Option"},
        {"name":"Name2", "kind":"namevalue", "type":["char", "choices={'Default','Choice1','Choice2'}"]}
     ]
  }
}

MATLAB 使用此函数签名描述来提供代码建议和自动填充。

如何使用函数签名信息

MATLAB 使用 JSON 文件中的函数签名信息在您键入时显示匹配的语法。您也可以通过按下 Tab 键来自动填充部分键入的文本。在命令行窗口中，MATLAB 不使用 JSON 文件显示与键入匹配的语法。

要体验一下代码建议，可从脚本或实时脚本调用 myFunc。建议会显示取自 JSON 文件的名称和用途。MATLAB 会指示参数是否为可选以及是否有多个建议（如第三个位置参数或一个名称-值对组）。列出名称-值对组选项。

向函数调用添加名称-值对组参数时，MATLAB 基于 JSON 文件提供选项。由于 'Name1' 定义为逻辑标量，因此 MATLAB 会自动填充选项（true 或 false）。MATLAB 基于 JSON 文件显示 'Name2' 参数的三个值。

多个签名

如果一个函数有许多语法，则可以在代码建议中将语法分组为多个函数签名（不考虑函数实现）。要为多个签名提供代码建议和自动填充，请在 JSON 文件中创建具有相同属性的多个函数对象。

以如下函数为例，它根据第二个输入的类采用不同代码路径。此函数仅用作代码建议的示例，因此不执行任何计算或错误检查。

function anotherFunc(arg1,arg2,arg3)
    switch class(arg2)
        case 'double'
            % Follow code path 1
        case {'char','string'}
            % Follow code path 2
        otherwise
            error('Invalid syntax.')
    end
end

从代码建议的角度来看，将函数视为具有两个函数签名。第一个签名接受两个必需的数值。第二个签名接受一个必需的数值，然后是一个字符或字符串，最后是一个必需的数值。要定义多个函数签名，请使用相同的属性（函数名称）在 JSON 文件中定义多个函数对象。

{
  "_schemaVersion": "1.0.0",
  "anotherFunc":
  {
     "inputs":
     [
        {"name":"input1",  "kind":"required", "type":["numeric"]},
        {"name":"input2",  "kind":"required", "type":["numeric"]}
     ]
  },
  "anotherFunc":
  {
     "inputs":
     [
        {"name":"input1",  "kind":"required", "type":["numeric"]},
        {"name":"input2",  "kind":"required", "type":[["char"],["string"]]},
        {"name":"input3",  "kind":"required", "type":["numeric"]}
     ]
  }
}

您也可以使用参数对象的 mutuallyExclusiveGroup 属性定义多个函数签名。通常情况下，实现多个函数对象更容易且更易读，但使用互斥组能够重用常见参数对象，如 input1。

{
  "_schemaVersion": "1.0.0",
  "anotherFunc":
  {
     "inputs":
     [
        {"name":"input1",  "kind":"required", "type":["numeric"]},
        {"mutuallyExclusiveGroup":
          [
            [
              {"name":"input2",  "kind":"required", "type":["numeric"]}
            ],
            [
              {"name":"input2",  "kind":"required", "type":[["char"],["string"]]},
              {"name":"input3",  "kind":"required", "type":["numeric"]}
            ]
           ]
        }
     ]
  }
}