Customize Code Suggestions and Completions

To customize code suggestions and completions for your functions, provide MATLAB® with information about your function signatures. Function signatures describes the acceptable syntaxes and allowable data types for a function. MATLAB uses this information to improve interactive features such as tab completion and function hints. Define this function information in a JSON-formatted file called functionSignatures.json.

For MATLAB to detect the function signature information, you must place functionSignatures.json in the folder that contains the function code. You can define signatures for multiple functions in the same file.

The functionSignatures.json file contains a single JSON object. JSON uses braces to define objects, and refers to objects as collections of name and value pairs. Since these terms are overloaded in context of function signatures, "property" is used instead of "name." The JSON object in functionSignatures.json contains an optional schema version and a list of function objects. Each function object contains a list of signature objects, and each signature object contains an array of argument objects. JSON uses brackets to define arrays.

To specify the optional schema version use _schemaVersion as the first property and the version number as its value. Specify the version number as a JSON string in the format major#.minor#.patch#, with each number specified as a nonnegative integer. The current schema version is 1.0.0. If the file does not specify a schema version, MATLAB assumes version 1.0.0.

If functionSignatures.json contains syntax errors, MATLAB displays an error message in the Command Window when it reads the file. Use the validateFunctionSignaturesJSON function to validate the functionSignatures.json file against the JSON schema and the MATLAB function signature schema.

Function Objects

To define information for a function, create a property that is the same as the function name. Its value is a signature object.

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

To define information for a class method or package function, use the full name of the function or method. Example properties are "MyClass.myMethod" or "myPackage.myFunction". You can define multiple function signatures for the same function by defining multiple function objects with the same property (function name). For more information, see Multiple Signatures.

Signature Objects

A signature object defines the input and output arguments and supported platforms for the function. The value of each property, except for the platforms property, is an array of argument objects.

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

Each signature can include the following properties.

PropertyDescriptionJSON Data Type of Value
inputs

List of function input arguments. MATLAB uses this property for code suggestions and completions.

Array of argument objects

outputs

List of function output arguments. MATLAB does not currently use this property for code suggestions and completions.

Array of argument objects

platforms

List of platforms that support the function. MATLAB does not present custom code suggestions and completions if the platform does not support the function.

The default is all platforms. Elements of the list must match an archstr returned from the computer function. The list can be inclusive or exclusive, but not both. Example values are "win64,maci64" or "-win64,-maci64".

String of comma-separated values

Argument Objects

Argument objects define the information for each of the input and output arguments.

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

The order that the inputs appear in the JSON file is significant. For example, in a call to the functionName1 function, in1 must appear before in2.

Each argument object can include the following properties.

 name – Name of argument

 kind – Kind of argument

 type – Class and/or attributes of argument

 repeating – Specify argument multiple times

 purpose – Description of argument

For more complicated function signatures, the following properties are available for each argument object.

 platforms – List of supported platforms

 tuple – Definition of set of arguments

 mutuallyExclusiveGroup – Definition of set of exclusive arguments

Create Function Signature File

This example describes how to create custom code suggestions and completions for a function.

Create a function whose signature you will describe in a JSON file in later steps. The following function accepts:

  • Two required arguments

  • One optional positional argument via varargin

  • Two optional name-value pair arguments via varargin

myFunc is presented to demonstrate code suggestions and does not include argument checking.

% 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

In the same folder as myFunc, create the following function signature description in a file called functionSignatures.json. The input names do not match the names in the body of myFunc, but are consistent with the help text.

{
  "_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 uses this function signature description to inform code suggestions and completion.

To experiment with code suggestions, start to call the function from a live script and observe the suggestions. For example, the names and purposes from the JSON file appear. MATLAB indicates when arguments are optional and if there are multiple suggestions available (such as the third positional argument or a name-value pair). Name-value pairs options are listed.

When adding a name-value pair argument to the function call, MATLAB presents the choices from the JSON file. Since 'Name1' is defined as a logical scalar, MATLAB populates the choices automatically (true or false). MATLAB takes the three values for the 'Name2' argument from the JSON file.

Multiple Signatures

If a function has many syntaxes, it can be helpful for code suggestions to group syntaxes as multiple function signatures (regardless of the implementation of the function). To provide code suggestions and completions for multiple signatures, create multiple function objects with the same property in the JSON file.

Consider the following function that follows different code paths depending on the class of the second input. This function is presented as an example for code suggestions, and, therefore, does not perform any computations or error checking.

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

From a code suggestions perspective, consider the function as having two function signatures. The first signature accepts two required numeric values. The second signature accepts a required numeric, followed by a character or string, and finally a required numeric. To define multiple function signatures, define multiple function objects in the JSON file with the same property (function name).

{
  "_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"]}
     ]
  }
}

Alternatively, you can define multiple function signatures using the mutuallyExclusiveGroup property of the argument object. Typically, it is easier and more readable to implement multiple function objects, but using mutually exclusive groups enables reuse of common argument objects, such as 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"]}
            ]
           ]
        }
     ]
  }
}

See Also

Related Topics

External Websites