histFS autocompletion won't show / missing

[matteozanettii]

Hi everybody, I am a student of CLED and I will join Data Science (hopefully) next year. I was exploring this repo and consequently found the discussion about function autocompletion made by @BoschiGiacomo , I wanna share a discovery I made that can be a starting point for one's that want to join this project. In the screenshot below we see that histFS autocompletion is missing/ not showing (using the example directly from edit histFS.m)

I tried to make a correction in the functionsignatures.json file as a way of learning the json file signatures autocompletion

"histFS":
{
"inputs":
[
{"name":"y", "kind":"required", "type":["numeric", "vector"], "purpose":"vector of n elements to bin"},
{"name":"nbins", "kind":"required", "type":["numeric", "vector"], "purpose":"the number of bins"},
{"name":"gy", "kind":"required", "type":["numeric", "vector"], "purpose":"identifier vector"},
{"name":"gylab", "kind":"ordered", "type":[["string"], ["cell"]], "purpose":"legend labels"},
{"name":"ax", "kind":"ordered", "type":"matlab.graphics.axis.Axes", "purpose":"plots into ax instead of gca"},
{"name":"barcolors", "kind":"ordered", "type":[["numeric"], ["char"]], "purpose":"colors of the bars"},
{"name":"W", "kind":"ordered", "type":["numeric", "vector"], "purpose":"Weights"}
],
"outputs":
[
{"name":"h", "type":"matlab.graphics.chart.primitive.Bar", "purpose":"Handles to the bar objects"}
]
}

But I am still struggling with making the json file, I hope to reach some better-prepared student that can handle this type of file better than me

[BoschiGiacomo]

Hello @matteozanettii, thanks for showing interest.
From your screenshot it's not clear what you mean by autocompletion missing/not showing, could you clarify the problem that you encountered?

It looks okay on my end.

I would be glad to answer every question that you have about this topic, and help you in the process of creating autocompletion for functions, so feel free to ask anything that's on your mind.

[matteozanettii]

Hi @BoschiGiacomo thank you for reaching out, it's a bit "complicated" to explain but I want to take as example balloonplot

It appears this little toggle menu where different options can be selected, in HistFS this part is missing, taking example gca (ax) option, described in the .m file

[BoschiGiacomo]

Thanks for making the problem clearer, and thanks for the interesting question; what you encountered is intended and well documented behaviour, let me explain:

The little menu that you see appearing, it's because those options are "name-value" arguments, that means that they can be inserted at any point after required and ordered arguments. The menu is there because there is not any specific order in which the arguments must be inserted, and their insertion can be omitted as well.

Meanwhile in the documentation of histFS all the optional input arguments are marked as positional which means that their position in the input matters, and this is why they are marked as "kind":"ordered" and not "kind:"namevalue" in the functionSignatures.json file.

For example in the documentation:

This means that the position of the optional input arguments matter, and the fact that we marked them as "ordered" is why MATLAB fixes them in place and doesn't give you the nice menu that you would expect for name-value arguments.

This also means that you can't omit those inputs when calling the function. If you wanted to omit them you would have to insert them as empty, but they cannot be omitted completely because inside the function, the interpretation of the values is tied to their position in the function call.

For example, if you wanted to omit the ax optional argument, but insert the next argument barcolors you would have to write:

histFS(y, nbins, gy, gylab, [], barcolors)

Note that there is an empty array in place of ax, because otherwise MATLAB would interpret the barcolors argument as ax.

Let me know if the explanation is clear, and make sure to tell me if you have any further questions.

[MarcoRianiUNIPR]

@matteozanettii welcome to this chat. @BoschiGiacomo thank you very much for your help.

In summary, positional arguments and optional Name,Value arguments are two different ways of passing inputs to a function.

As Giacomo said, positional arguments are identified by their order in the function call.
For example in the help of gplotmatrix

siz is a positional argument and must be in position 6 when calling gplotmatrix

For example, to control the size of the points the code below

rng(100) 
X=randn(100,3);
% Set the size of the points to 30
% This is the 6th positional input argument
gplotmatrix(X,[],[],[],[],30)

produces

On the other hand Name,Value arguments are specified using parameter names, not position.

For example

In this case the two instructions below give the same answer

spmplot(X,"typespm","lower","dispopt","box");
spmplot(X,"dispopt","box","typespm","lower");

As usual the discussion and the opinion of each person is welcome. Do you prefer positional or "Name",Value arguments?

[BoschiGiacomo]

Personally, I don't feel much difference between positional and name-value arguments when it comes to optional inputs. If positional arguments allow us to create simpler and lighter input validation logic inside functions that don't have many optional inputs, I believe the benefits outweigh the slightly less practical input method. Of course for complicated functions with a lot of options, I feel that name-value arguments are definitely the way to go.

[matteozanettii]

Hi @MarcoRianiUNIPR and @BoschiGiacomo ,

Thank you both for the extremely clear explanation. The distinction between positional and Name-Value arguments is much clearer to me now, and I appreciate the examples provided.

Regarding the Professor's question: from a student and future user perspective, I personally prefer Name-Value arguments. While positional arguments might allow for lighter internal logic, Name-Value pairs significantly improve code readability and self-documentation. They also prevent common mistakes, such as miscounting the number of empty brackets [] required to reach a specific optional input in a long signature