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

[John W. Eaton]

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

"I suggest that it should support both in the sense that it looks in both
places, so if some older classdef have the documentation before the function
and not inside it, then get_help_text should return the one before instead of
returning that documentation is not present."

I see the following method in the file
statistics/inst/Classification/ConfusionMatrixChart.m
(https://github.com/gnu-octave/statistics/blob/167b7e0c1b00b3e0ab887fbd16a420822dac8897/inst/Classification/ConfusionMatrixChart.m):


  methods (Access = public)
    ## class constructor
    ## inputs: axis handle, a confusion matrix, a list of class labels,
    ##         an array of optional property-value pairs.
    function this = ConfusionMatrixChart (hax, cm, cl, args)
      ## class initialization
      this.hax = hax;


and


    ## -*- texinfo -*-
    ## @deftypefn  {ConfusionMatrixChart} {} sortClasses (@var{cmc},
@var{order})
    ## Sort the classes of the @code{ConfusionMatrixChart} object @var{cmc}
    ## according to @var{order}.
    ##
    ## Valid values for @var{order} can be an array or cell array including
    ## the same class labels as @var{cm}, or a value like @code{"auto"},
    ## @code{"ascending-diagonal"}, @code{"descending-diagonal"} and
    ## @code{"cluster"}.
    ##
    ## @end deftypefn
    ##
    ## @seealso{confusionchart, linkage, pdist}
    function sortClasses (this, order)

      ## check the input parameters
      if (nargin != 2)
        print_usage ();
      endif


so if I understand correctly, the rules you are proposing would select "check
the input parameters" as the docstring for the constructor and "check the
input parameters" as the docstring for the sortClasses method.

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?  Currently, that tag is only used as a marker for
deciding whether to process the docstring with the Texinfo formatter, not to
decide whether it is a docstring.

"The other issue is that it feels a bit counter-intuitive to generally have
the documentation for general functions before the function block in the m
file, and in classdef files, requiring the documentation to be inside the
function block."

For ordinary functions, I believe Matlab still selects either the first
comment in a .m file, whether it is before or after the "function" keyword. 
It's always made sense to me to put that comment first, after the copyright
statement.


    _______________________________________________________

Reply to this item at:

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

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