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

[Andreas Bertsatos]

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

The documentation of the constructor in the ConfusionMatrixChart is not n
actual documentation but merely comments, since in earlier version (7.2 and
8.2) that I work it didn't make any difference since you can't retrieve the
constructor's help

>> help ConfusionMatrixChart.ConfusionMatrixChart
error: unknown package 'ConfusionMatrixChart'
error: called from
    <unknown>
    help at line 102 column 20

But I will make the necessary changes in time for Octave 9.1.

Although I explicitly use texinfo for help documentation, I don't think the
get_help_text function should check for this. My suggestion is that it favors
the text before rather than after the function's initial declaration.
Personally, I prefer to have the documentation before and not inside the
function. Perhaps it is just a matter of habit, since I am used to the way
Octave functions' source files contain their documentation in contrast to
MATLAB.

"It's always made sense to me to put that comment first, after the copyright
statement."

I couldn't agree more with this statement.

"Or, are you suggesting the additional complication of checking the comment
for a leading "-*- texinfo -*-" tag and only using (or preferring it) as the
docstring if it is present?"

I don't know how much it adds to the complexity of the code or if it raises
any computational speed issues, but that would be ideal, since it would be
more robust in that it would return the 'appropriate' text block as
documentation. Because, different users might have done things differently
(currently or in the past) but if you have a "## -*- texinfo -*-" block, then
you can be sure that this is the help documentation and not some code comment,
regardless where the user might have placed it (before or after the "function"
statement).




    _______________________________________________________

Reply to this item at:

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

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