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

[John W. Eaton]

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

I think it's important to preserve compatibility here.  Otherwise, just like
the "for i = zeros (0, N) ... end" issue, we will just periodically get bug
reports about this when Octave displays the "wrong" text for "help cls.meth"
and users will get the impression that we are dumb for not making Octave to
the Right Thing (and for these users, the Right Thing is always whatever it is
that Matlab does).

It seems the only conflict we are talking about here is the one that occurs
when there are comments just above and below the function keyword for a method
in a class.

There may be more options, but I can see at least three possibilities for
resolving the conflict and preserving Matlab compatibility:

1. If the comment above the function uses "#" comment characters, do the
incompatible Octave-specific behavior.  The code won't work in Matlab anyway. 
If it uses '%' comment characters, do the Matlab-compatible thing and choose
the comment in the function body.  That doesn't help those who want Octave to
select the comment above the function keyword but happen to prefer '%' over
'#'.
2. If the comment above the function keyword starts with "-*- texinfo -*-" (or
some other agreed-upon tag) then select that as the help text.  That doesn't
help those who just want simple plain-text doc strings or don't know about the
special tag.
3. Use a configuration option for the parser so users can configure what they
want the behavior to be.  That doesn't help those who wish to use files that
were written expecting behavior different from what the configuration option
specifies.

Which one is least bad?  Maybe the second one if we check the comment above
the function keyword for *either* the "-*- texinfo -*-" tag or some other tag
like "-*- doc -*-"?


    _______________________________________________________

Reply to this item at:

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

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