[Octave-bug-tracker] [bug #65220] get_help_text returns docstring from parent methods

[Rik]

Follow-up Comment #27, bug#65220 (group octave):

For what it's worth, I favor consistency over Matlab-compatibility here. 
Having coded for year's with Matlab's convention of having the first comment
above the "function" keyword be the help text, I find I want to do the same
when that "function" keyword is inside a classdef definition.  It's also the
way I code in other languages like C++ where I put the overview of the
function above its implementation.  Within the implementation I favor one-line
comments explaining what is going on, rather than a treatise on the purpose of
the function.

Here is the test function that I have been using (also attached).


classdef cdef_help
% class CDEF_HELP  A test class for checking help function
%
%   This comment block contains general help for the cdef_help class:
%
%   This general help text should be shown for "help cdef_help".
%
% @seealso{cdef_help, disp}
  properties
    % name: help for property NAME.
    % Type "help cdef_help.name"
    name
    age   % age: help for property AGE.  Type "help cdef_help.age"
  end

  methods

    function obj = cdef_help (n, a)
      % cdef_help: constructor help text
      %
      %  This help text should be shown for "help cdef_help.cdef_help".
      if (nargin ~= 2)
        obj.name = 'default';
        obj.age = 42;
      else
        obj.name = n;
        obj.age = a;
      end
    end

    % meth1: method help tex above function
    %
    %  This help text should be shown for "help cdef_help.meth1".
    function obj2 = meth1 (obj, n)
      obj2 = n + obj;
    end
    
    function obj2 = meth2 (obj, n)
      % meth2: method help tex below function
      %
      %  This help text should be shown for "help cdef_help.meth2".
      obj2 = n - obj;
    end

    % disp: method help text ABOVE function
    %
    %  This help text should be shown for "help cdef_help.meth1".
    function disp(obj)
      % disp: method help text BELOW function
      %
      %  This help text should be shown for "help cdef_help.meth1".
      fprintf('class name = "%s", age = %d\n', obj.name, obj.age)
    end
  end
end


The current behavior of Octave, when comments both ABOVE and BELOW the
"function" keyword is to use the comment above.  I'm okay with that, but I
also am less concerned about exact Matlab compatibility than others.

(file #55644)

    _______________________________________________________

Additional Item Attachment:

File name: cdef_help.m                    Size:1 KB
    <https://file.savannah.gnu.org/file/cdef_help.m?file_id=55644>


    AGPL NOTICE

These attachments are served by Savane. You can download the corresponding
source code of Savane at
https://git.savannah.nongnu.org/cgit/administration/savane.git/snapshot/savane-3112ec7181a7018604fb7b25b2201235b3bdfb6a.tar.gz


    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?65220>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/