2

I'm writing MATLAB functions for use by others. I know how to use nargin, varargin, etc. to create a function with variable number of inputs.

The function I'm currently writing is recursive and I need to pass an argument to handle the recursion, but the user should never pass anything in for that argument (or they should pass in the non-intuitive starting value, but they don't need to be distracted by that). I want to 'hide' this argument from the user, so that when they're writing code to use this function and MATLAB pops up that little yellow window that tells them what arguments the function takes, it just prompts them for the arguments they care about.

To be more explicit, when you type rand(, MATLAB pops up a little help window with

rand()
rand(n)
rand(sz1,...,szN)
...

My function recursively builds a matrix and I've currently defined it this way:

function ret = M(arg1, arg2, HideThisRecursiveArgument)
  % code that sets the starting value for HideThisRecursiveArgument when it's not passed
  % code that calls M(...) again with a different recursion value
end

When the user types M(, I want MATLAB's little help popup to display the usage as:

M(arg1, arg2)

(arg1 and arg2 are named in a self descriptive manner, so this would be a sufficient 'help page' for my function.)

How can I document this usage so MATLAB's function usage help popup will display this to the user?

If I use varargin, the user might get distracted/confused by trying to figure out what else could be passed in, so that's unsatisfactory. I've tried defining my function with 2 arguments and then looking for a 3rd when it's called, but MATLAB doesn't like that.

Edit I've found the Add Help for Your Program page, and if the user uses the help command or clicks the More Help... link in that yellow usage popup, I can control what they see there, but this doesn't tell me how to control what appears on the usage popup.

Travis Bemrose
  • 379
  • 1
  • 12
  • Related: https://www.mathworks.com/matlabcentral/answers/338247-how-to-implement-function-hints-in-your-code – Travis Bemrose Mar 06 '20 at 20:52
  • 1
    Not sure why Edric's answer got deleted by a moderator. He pointed to https://uk.mathworks.com/help/matlab/matlab_prog/customize-code-suggestions-and-completions.html . It basically does what the question asks for, but in MATLAB Live Scripts. When typing `myfun(` in the editor it still shows the arguments as named in the code, unlike some built in ones like `rand(`. – Daniel Mar 07 '20 at 11:52

2 Answers2

3

I would opt for two separate interfaces, the function to be called externally and your internal recursive function with the hidden argument:

function z=foo(x,y)
    z=internalfoo(x,y,pi);   
end
function z=internalfoo(x,y,secret)
    if x>y
        z=internalfoo(y,x,secret);
    else
        z=secret*x;
    end
end

You can place both in the same file foo.m, only the foo() can be called externally (unless you do nasty stuff). Above example contains a local function. Depending on your task a nested function with shared variables is sometimes practical for recursion.

Daniel
  • 36,610
  • 3
  • 36
  • 69
  • 1
    Thanks! That meets my immediate need for this function. I'll want to be able to output multiple lines of text in that context help for other functions, so I'll leave the question open in hopes of a better solution. – Travis Bemrose Mar 06 '20 at 20:51
  • Oh you are right, totally missed that part of your question. First reading your question I thought that was just an extract of "help rand", but it is some different text. – Daniel Mar 06 '20 at 21:29
2

Regarding the second part of your question, look into functionSignatures.json. This allows you to customize the code suggestions and completions, unfortunately only within the Live Editor.

Examples incl. multiple signatures for the same function can be found in the doc.

Note: I had to restart MATLAB prior to experimenting in the Live Editor

Additionally, if you use R2021a checkout the new arguments syntax for declaring function argument validation, see doc.

cuda12
  • 600
  • 3
  • 15