Create help for method with arguments

Question

Vasco 2022-3-21

0
链接

此问题的直接链接

https://ww2.mathworks.cn/matlabcentral/answers/1676564-create-help-for-method-with-arguments

编辑： Matt J 2022-3-21

I like to document my functions, such that on pressing on F1, it shows description of the function, and its parameters.

The recently introduced arguments block allows to define arguments sizes and types. What is the best practice to document these arguments?

I preferably like to keep the defintion and the documentation at the same location, like in the example below:

function [m,s] = twoStats(x)
    % Test for help
    arguments
        x (1,:) {mustBeNumeric}  % Argument 1, the array to calculate statistics on
    end
    m = mean(x,"all");
    s = std(x,1,"all");
end

Preferred output:

doc twoStats
Test for help
Arguments:
- x: Argument 1, the array to calculate statistics on

0 个评论
显示 -2更早的评论隐藏 -2更早的评论

请先登录，再进行评论。

请先登录，再回答此问题。

Answer 1

Matt J 2022-3-21

0
链接

此回答的直接链接

https://ww2.mathworks.cn/matlabcentral/answers/1676564-create-help-for-method-with-arguments#answer_923149

在 MATLAB Online 中打开

function [m,s] = twoStats(x)
    % Test for help
    %
    %Arguments:
    % - x: Argument 1, the array to calculate statistics on
    
    arguments
        x (1,:) {mustBeNumeric}  % Argument 1, the array to calculate statistics on
    end
    m = mean(x,"all");
    s = std(x,1,"all");
end

2 个评论
显示无隐藏无

Vasco 2022-3-21

Ok, this seems the trivial solution, just copy paste the information from the arguments block to the documentation block. However, now the documentation and definition is split to different places.

Matt J 2022-3-21

编辑：Matt J 2022-3-21

在 MATLAB Online 中打开

There is no other solution. The help text can only be in one place. You could of course, write tools that will semi-automate the documentation process. Once you have the argument text copied to the clipboard, code like the following can be used to parse it into the format you want:

>> contents = clipboard('paste')

contents =

'x (1,:) {mustBeNumeric} % Argument 1, the array to calculate statistics on'

>> out = "% - "+extractBefore(contents,' ')+" "+extractAfter(contents,'%'); disp(out)

% - x Argument 1, the array to calculate statistics on

请先登录，再进行评论。