Fetch the repository succeeded.
MATLAB 函数签名器 (FUNCSIGN) ，在规范注释格式的基础上为函数文件或类文件自动生成函数签名，并保存至functionSignatures.json。
函数签名能够允许使用者在编辑器调用这些（自定义）函数的时候具备代码提示和自动填充功能，提升编程体验，更多介绍请阅读 自定义代码建议和自动填充 - MATLAB & Simulink - MathWorks 中国。
👍自定义函数代码提示与自动填充：
为了简化自动化步骤，需要对MATLAB的函数文件和类文件的注释格式进行一定的限制和规范，以下为文件注释模板：
function returnValue = functionName(R1, R2, R3, O1, O2, varargin)
%functionName 函数的简要说明
%
% 函数详细说明
%
% Syntax: (这里添加函数的调用格式, `[]`的内容表示可选参数)
% returnValue = functionName(R1, R2, R3 ...
% [, O1, O2 ...
% , 'Coeff', 100 ...
% , 'k', 1.0 ...
% , "Method", "way1"]);
%
% Params:
% - R1 [required] [[char], [string]] R1是char或string
% - R2 [required] [numeric; size=2,2] R2为一个2x2的数值矩阵,注意用分号隔开
% - R3 [required] 可以省略参数数据格式
% - O1 [ordered] [numeric; vector] 可选参数O1
% - O2 [ordered] [numeric; nrows=2] 可选参数O2, 函数简要描述将会被记录
% 可在此处添加O2的详细说明，但是不会被记录到json文件中。
%
% - Coeff [namevalue] [numeric] namevalue对
% 当一个函数存在太多参数设置时, 推荐使用namevalue, 提高可读性, 不需要记忆函
% 数参数位置;
% - k [namevalue] [[numeric], [numeric, choices]] 选项设置
% * 1.0 可添加选项简要描述, 但是不会别记录
% * 2.0 没有用引号括起的选项不能包含空格
% * 3.0 程序会尝试将选项转换为数值，若失败则转换为字符串
% - Method [namevalue] [char; choices] 选项设置
% * 'way1' 方法1
% 选项之间可换行或添加其他说明
%
% * 'way2' 方法2
%
% Return:
% - returnValue 返回值
%
% Note:
% 这里可以添加其他描述
%
% Matlab Version: R2021b
%
% See also:
% myadd, myfun, myfun2, myfun3
returnValue = R1; % 正式代码与注释之间留一个空行
end
关于模板的几点要求❗和建议✔ ：
❗ 函数文件和类文件必须遵循MATLAB语法规则，不能有语法错误：
函数文件function必须位于文件首行，且函数名需与函数文件名保持一致；
类文件classdef 位于文件首行且类名与类文件名一致；
✔ 建议文件注释从文件第二行开始，% 从第一列开始，后跟函数名或类名以及文件简要描述；
✔注释中存在一些关键字，例如 Syntax 后跟函数调用格式，Params后跟函数输入参数描述，Return 后跟返回值等。这些关键字中只有 Params 是必要的，其他关键字是可选的（也就是说可以自定义增删减改）；
❗ Params关键字后为函数参数描述内容。注释模板必须要有关键字 Params （关键字后可以紧跟冒号:），程序检测到Params关键字后才会解析后续行的函数参数描述，直到注释结束或检测到一个新的关键字；
❗ 在 Params 后，其他关键字之前的行为函数参数描述，函数的每一个输入参数都需要独立占一行，并且按照如下格式：
参数标识符 参数名称 [参数类型] [数据格式] 参数简要说明
参数标识符 默认为 -，检测到此标识符的行才会被解析，否则会跳过此行的，因此允许函数参数描述行之间添加一些对参数的具体描述（具体例子见模板）；
[参数类型] 和 [数据格式] 可以省略，程序会用默认值（[required]和[numeric]）进行替代，但是两者不能互换位置；
参数简要说明 会被记录到 json 文件；
✔文件注释结尾处与代码之间留一个空行；
与 自定义代码建议和自动填充 - MATLAB & Simulink - MathWorks 中国 规定相同，目前支持以下三种类型：
✔ 参数类型可以使用首字母缩写，即[r]/[R]来表示[required]，[o]/[O]来表示[orderd]，[n]/[N]来表示[namevalue]；
✔ 参数类型 kind 可以省略，默认为 [required]；
❗ 参数类型 kind 必须位于数据格式 type 之前；
❗ 根据 MATLAB 的要求，函数参数需要按照 required、orderd、namevalue类型依次排列，即函数输入先放必要参数，再放可选参数，最后放namevalue参数。
与 自定义代码建议和自动填充 - MATLAB & Simulink - MathWorks 中国 基本一致，但又有几点不同，我们将结合 MATLAB 的说明文档进行说明：
type 属性可以定义参数是哪个类以及参数必须具有哪些属性。
要匹配一个类或属性，请使用单个 JSON 字符串。例如，如果参数必须是数值，则指定 "type":"numeric"。
注释数据格式为
[numeric]
要匹配所有类或属性，请使用 JSON 字符串列表。例如，如果某个参数必须既是数值又是正数，则指定 "type":["numeric", ">=0"]。
注释数据格式为
[numeric; >=0]
要匹配多个类或属性中的任意多个，请使用 JSON 字符串列表的列表。在内层列表，MATLAB 对各值执行逻辑 AND 运算。在外层列表，MATLAB 对各值执行逻辑 OR 运算。例如，如果参数必须要么是正数，要么是 containers.Map 对象，则指定 "type":[["numeric", ">=0"],["containers.Map"]]
注释数据格式为
[[numeric; >=0], [containers.Map]]
提供参数选项 ["char", "choices={'way1', 'way2'}"]
注释数据格式为
[char; choices]，选项由选项行提供
注释数据格式总结为：
; 隔开，它们是并&&的关系；,隔开，不同列表是或 || 的关系；✔ 数据格式 kind 可以省略，则默认为 [numeric]。
❗ 数据格式 kind 必须位于参数类型 kind 之后。
当数据格式中包含 choices时，程序会将此行(包含choices)与下一个包含参数描述/关键字的行之间的行识别为选项行。每一个选项独占一行，选项的描述格式为：
选项标识符 选项名称 选项说明
*，检测到此标识后此行才会被解析，因此选项之间可以留空或者添加具体的选项描述；'或"括起（选项名称可以有空格），或者不用引号（选项名称不允许有空格），选项名称会被记录到 json，程序会尝试将选项名称转换为数字（如果可以），若转换失败则为字符串；❗ 选项标识符不能与参数标识符相同！
例 1：
- Method [namevalue] [choices] 选择一个方法
* 'add' 方法1
* 'subtract' 方法2
* 'multi' 方法3
转换 json 字符串为
"choices={'add', 'subtract', 'multi'}"
例 2：
- Method [R] [char; choices] 选择一个方法
* add 方法1
* subtract 方法2
* multi 方法3
转换 json 字符串为
"char", "choices={'add', 'subtract', 'multi'}"
例 3：
- Coeff [R] [int; choices] 选择一个方法
* 1
* 2
* 3
转换 json 字符串为
"int", "choices={1, 2, 3}"
可执行程序为 dst/signfunc.exe，其运行指令为
signfun.exe <DirPath> [-ag -] [-op *] [-ver 1.0.0] [-info on/off] [-kind required] [-type numeric]
其中，必须指定目标文件夹的路径 DirPath，其他几项为可选项:
❗ 注意，需要将可执行程序的路径添加到系统环境路径中。
封装的m函数为 dst/hs_signfunc.m，其调用格式为
status = hs_signfunc(dir_path ...
[, "Verbose", true ...
, "ArgSym", '-' ...
, "OptSym", '*' ...
, "Version", "1.0.0" ...
, "DefaultKind", 'required' ...
, "DefaultType", {"numeric"}]);
具体的函数参数说明见函数文件 hs_signfunc.m。
注意：
❗ 需要将可执行程序 signfunc.exe 的路径添加到系统环境路径中；
❗ 需要将m函数文件 hs_signfunc.m 添加到 MATLAB 路径中。
程序运行后会在指定目录下生成函数签名文件 functionSignatures.json 和日志文件 funcsigner.log。
可以调用 validateFunctionSignaturesJSON(json_path) 来检验函数签名文件格式是否正确。检查格式无误后，可能需要重启 MATLAB 才能激活自定义函数代码提示功能。
编译环境：
✔ 软件安装好后，打开VSCode进入当前文件夹，打开命令面板，执行 cmake configure，在底部改为Release模式，再执行 cmake build target 后选择 install。
依赖第三方库（已放置到 thirdparty）
当然，也可以通过命令行的方式进行编译
mkdir build cd build cmake -DCMAKE_BUILD_TYPE=Release .. cmake --build . --config Release -A x64 cmake install
等待编译完成后可执行程序保存在 dst，将其添加到系统路径和MATLAB路径，即可使用。
由于 jsoncpp 不能按照插入顺序进行输出，在调用 validateFunctionSignaturesJSON 会有如下信息。但经实测，函数签名仍有效；
"_schemaVersion" 必须是文件中的第一个属性。
为什么不提供 mex 文件
mex 接口对中文支持实在不友好，输入到终端的字符顺序又有点乱😂，目前还没有解决方法；使用
system调用可执行程序已经很好满足需求了，不再考虑通过mex来封装了。
跨平台支持
注释模板的函数签名文件：
{
"_schemaVersion" : "1.0.0",
"functionName" :
{
"inputs" :
[
{
"kind" : "required",
"name" : "R1",
"purpose" : "R1是char或string",
"type" :
[
[
"char"
],
[
"string"
]
]
},
{
"kind" : "required",
"name" : "R2",
"purpose" : "R2为一个2x2的数值矩阵,注意用分号隔开",
"type" :
[
"numeric",
"size=2,2"
]
},
{
"kind" : "required",
"name" : "R3",
"purpose" : "可以省略参数数据格式",
"type" :
[
"numeric"
]
},
{
"kind" : "ordered",
"name" : "O1",
"purpose" : "可选参数O1",
"type" :
[
"numeric",
"vector"
]
},
{
"kind" : "ordered",
"name" : "O2",
"purpose" : "可选参数O2, 函数简要描述将会被记录",
"type" :
[
"numeric",
"nrows=2"
]
},
{
"kind" : "namevalue",
"name" : "Coeff",
"purpose" : "namevalue对",
"type" :
[
"numeric"
]
},
{
"kind" : "namevalue",
"name" : "k",
"purpose" : "选项设置",
"type" :
[
[
"numeric"
],
[
"numeric",
"choices={1.0, 2.0, 3.0}"
]
]
},
{
"kind" : "namevalue",
"name" : "Method",
"purpose" : "选项设置",
"type" :
[
"char",
"choices={'way1', 'way2'}"
]
}
]
}
}
此处可能存在不合适展示的内容，页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容，可点击提交进行申诉，我们将尽快为您处理。