Документация

Объекты функций

Чтобы определить информацию для функции, создайте свойство, совпадающее с именем функции. Его значение является объектом подписи.

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

Чтобы определить информацию для метода класса или функции пакета, используйте полное имя функции или метода. Например, определите метод класса myMethod и функция пакета myFunction.

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

Можно определить несколько сигнатур функций для одной функции или метода, определив несколько объектов функций с одним и тем же свойством (имя функции или метода). Дополнительные сведения см. в разделе Несколько подписей.

Объекты подписи

Объект сигнатуры определяет входные и выходные аргументы и поддерживаемые платформы для функции. Значение каждого свойства, за исключением platforms - массив объектов-аргументов.

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

Если указан метод экземпляра, например myClass.myMethod в файле JSON - один из элементов в inputs должен быть объектом myClass. Обычно этот объект является первым элементом. MATLAB поддерживает предложения и дополнения кода для указанного метода при вызове его с помощью точечной нотации (b = myObj.myMethod(a)или нотация функции (b = myMethod(myObj,a)) синтаксис.

Каждая сигнатура в файле JSON может содержать следующие свойства.

Объекты аргументов

Объекты Argument определяют информацию для каждого из входных и выходных аргументов.

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

Порядок отображения входных данных в файле JSON является значительным. Например, в вызове functionName1 функция, in1 должен появиться до in2.

Каждый объект аргумента может содержать следующие свойства.

 name - Имя аргумента

 kind - Вид аргумента

 type - Класс и/или атрибуты аргумента

 repeating - Указать аргумент несколько раз

 purpose - Описание аргумента

Для более сложных сигнатур функций для каждого объекта аргумента доступны следующие свойства.

 platforms - Список поддерживаемых платформ

 tuple - Определение набора аргументов

 mutuallyExclusiveGroup - Определение набора исключительных аргументов

Создать файл подписи функции

В этом примере описывается создание пользовательских предложений кода и дополнений для функции.

% 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

{
  "_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 использует информацию о сигнатуре функции в файле JSON для отображения соответствующих синтаксисов при вводе (подсказки функций). Частично введенный текст можно заполнить, нажав клавишу Tab (заполнение вкладки). В окне команд или редакторе MATLAB не использует файл JSON для отображения подсказок функций. Поведение подсказок функций и завершения табуляции суммировано в таблице.

В MATLAB Online™ редактор ведет себя так же, как и Live Editor.

Несколько подписей

Если функция имеет много синтаксисов, может быть полезно для предложений кода группировать синтаксисы как несколько сигнатур функций (независимо от реализации функции). Чтобы предоставить предложения кода и дополнения для нескольких сигнатур, создайте несколько объектов функций с одним и тем же свойством в файле 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"]}
            ]
           ]
        }
     ]
  }
}