Rethink help texts on methods

[edovanveen]

Right now self is missing from help texts on methods, e.g.:

classdef NrnRef < handle    
    methods
        function self = NrnRef(obj)
        % Initialize NrnRef
        %   NrnRef(obj) constructs a Matlab wrapper for C++ NrnRef obj
            ...
        end
        function value = get(self, ind)
        % Get value.
        %   value = get()
        %   value = get(index)
            ...
        end
    end
end

It is probably better to do something like:

classdef NrnRef < handle    
    methods
        function self = NrnRef(obj)
        % Initialize NrnRef
        %   nrn_ref = NrnRef(obj); constructs a Matlab wrapper for C++ NrnRef obj
            ...
        end
        function value = get(self, ind)
        % Get value.
        %   value = nrn_ref.get()
        %   value = nrn_ref.get(index)
            ...
        end
    end
end

Alternatively we can follow the recommendation in https://doc.monkeyproofsolutions.nl/code-checker-for-matlab/monkeyproof-matlab-coding-standard/v1.3/Layout/help_text.html. However, because we work with dynamic methods added through subsref, method(object) does not work, but object.method() does...

[ramcdougal]

I have no idea what the MATLAB documentation convention is... but I like this idea in that it makes clear that you probably want to hang on to the returned value so it's not garbage collecting whatever you just created.

[edovanveen]

I have no idea what the MATLAB documentation convention is... but I like this idea in that it makes clear that you probably want to hang on to the returned value so it's not garbage collecting whatever you just created.

There is no convention, as far as I know!