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

[Andreas Bertsatos]

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

There are four possible combinations of comments being present before and
after the function declaration

1)
## documentation or comment
function someFun
## documentation or comment
...
endfunction

2)
%% documentation or comment
function someFun
## documentation or comment
...
endfunction

3)
## documentation or comment
function someFun
%% documentation or comment
...
endfunction

4)
%% documentation or comment
function someFun
%% documentation or comment
...
endfunction

Since `#` is explicit to Octave, I would suggest that get_text_help should
check both before and after the function statement and if either of the
positions have comment lines starting with `#` it should return it as the help
documentation. If both positions have `#` comment lines, then it should
consider the above for being the documentation (let's say the Octave way). If
both positions have `%` comment lines then it should do the MATLAB way and
return the comments below the function statement as the documentation.

This way, code written for both MATLAB and Octave will behave similarly
without the programmer or the user having to do something about it.
Furthermore, code written for explicitly for Octave would still have to follow
the same documentation rules that have been established so far and there is no
compatibility breaking.

@jwe If you would like to take an extra step to make it even more robust for
Octave code, then just in the first case, where both positions have `#`
comment lines, we could check both comment blocks for the -*- texinfo -*- tag
and return whichever contains it, otherwise (if none has it) prefer the
comment block before the function declaration.

I think this is the best compromise between adjusting for Matlab compatible
behavior and maintaining backwards compatibility with Octave code.

I am really against a configuration option solution as I think it will
introduce more mess and bug reports rather than solve our current problems
with correctly parsing help documentation from existing and future classdef
files.


    _______________________________________________________

Reply to this item at:

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

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