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

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

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

{
  "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 может включать следующие свойства.

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

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

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

В Online™ MATLAB Редактор ведет себя так же, как и 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"]}
            ]
           ]
        }
     ]
  }
}