R2018a functionSignatures.json (user function tab complete) not working as documented outside of live-script

In a recent thread, I came across a mention of a new feature in R2018a: tab completion suggestions for user-defined functions. (release notes link to this feature)

I applaud this development. I know I am not the only one complaining that it didn't already exist. So I immediately tried to check it out. I used the guide linked in the release notes, which states: "To experiment with code suggestions, start to call the function from a live script and observe the suggestions."

That suggests that it's also possible to use this outside of live scripts, but they just suggest you use that. I don't appear to be the only one thinking that, as suggested by Sean de Wolski: "While I can't talk about the future, if you look at 18a, there is new infrastructure for adding function signatures for code complete/suggest especially in regards to the live editor."

But I failed to get it to work. In the normal editor I only got the normal header-derived hint, and in the live script I could only get a single input type, instead of the two included in my JSON file. What am I doing wrong? Or is the feature not yet at the level the documentation has us believe? Is this a bug that I should report (there aren't any about this yet)?

(Function header, result in live script, and JSON file below and in zip)

function outfilename=WBM(filename,url_part,varargin)
% syntax:
% outfilename=WBM(filename,url_part)
% outfilename=WBM(___,options)
% outfilename=WBM(___,Name,Value)

.

{
  "WBM":
  {
    "inputs":
    [
      {"name":"filename", "kind":"required", "type":["char"],
      "purpose":"Target file name"},
      {"name":"url_part", "kind":"required", "type":["char"],
      "purpose":"URL of the file/website"},
      {"name":"options",  "kind":"ordered",  "type":["struct"],
      "purpose":"Struct containing the options"}
    ]
  },
  "WBM":
  {
    "inputs":
    [
      {"name":"filename",  "kind":"required",  "type":["char"],
      "purpose":"Target file name"},
      {"name":"url_part",  "kind":"required",  "type":["char"],
      "purpose":"URL of the file/website"},
      {"name":"date_part", "kind":"namevalue", "type":["char"],
      "purpose":"Partial or complete date of the capture"},
      {"name":"tries",   "kind":"namevalue", "type":["numeric","numel=3"],
      "purpose":"Number of times a [load,save,timeout] is allowed"},
      {"name":"verbose",  "kind":"namevalue", "type":["numeric","scalar","integer"],
      "purpose":"The amount of text displayed"},
      {"name":"m_date_r",  "kind":"namevalue", "type":["char", "choices={'ignore','warning','error'}"],
      "purpose":"Missing date response"},
      {"name":"response",  "kind":"namevalue", "type":["char"],
      "purpose":"Cell with responses"},
      {"name":"ignore",  "kind":"namevalue", "type":["char"],
      "purpose":"HTML error codes to be ignored"}
    ]
  }
}

[Ken Atwell]

Two things to check:

1. Be sure that the functionSignatures.json is in the same folder as where your WMB function is located.
2. If you have just created this file, you may need to restart MATLAB before it becomes visible. After the restart, you should be able to subsequently update the file without a restart.

[Rik]

I was really hoping that would fix it, but even with a reboot that doesn't fix it. I also find it odd that it does parse the second definition (as it loads the descriptions etc), but that it still shows the options variable as the last option, even if it is in the Name,Value part.

Is this even supposed to work outside of the live script, or is that limitation just not clearly documented?

[Ken Atwell]

"options" is a catch-all name used to indicate the existence of trailing name/value pairs. I can see how this is confusing in your particular case since you happened to use "options" as a name in your signature too. With the JSON definition you give, I would expect the Live Editor to display to something like the following:

After you enter a few arguments, "options" will still be used to indicate that more name/value pairs are possible:

You've noticed only the Live Editor displays function hints from your JSON definition. Speaking specifically of R2018a, The Command Window and plain-text editor do not get their hints from JSON definitions. While I cannot speak to future plans, I would reasonably expect that, over time, JSON information will be used more broadly. I'll see what can be done to document this more clearly.

However, even in R2018a, your JSON definition will used for the purposes of tab completion, for example:

Does that clarify things a bit?

[Rik]

Yes, thanks a lot, that does clarify my main questions.

There is one thing that's not yet fully clear to me: the current doc sounds to me as if I should see multiple lines of suggestions (one line per entry, just like e.g. plot would). Can you confirm I'm reading it incorrectly, or is there something else I'm missing?

[Ken Atwell]

Yes, you can see multiple signatures. In your specific case, you would if you rename your "options" argument to something else, say "optionsStruct". You currently see only one line because you'd otherwise get two identical-looking signatures... hardly helpful.

[Rik]

Thanks a lot, I just tested it on R2017b, and it seems to work as intended. I would suggest changing the default display name of Name,Value pairs to "Name,Value", instead of "options". That would have removed a lot of ambiguity for me, and also automatically solves the problem of two definitions merging in the display when one is named "options". (I have just file a feature request to that effect)

If you move one of your comments to the answer section I can mark it as accepted answer, thank you for your time.

Answer 1

[Ken Atwell]

See the "comments" section for more discussion. In this particular case, the use of the argument name "options" is making the display a little ambiguous, since "options" is also generically used as the name for trailing name/value pairs (and, more rare, trailing flags).

In R2018a specifically, JSON definitions are use to display:

• Function hints and suggested completions in the Live Editor
• Tab-completion only in the command window and plain-text editor. Function hints still use older facilities.