bugGNU Octave - Bugs: bug #65259, Don't say documentation for class...

 
 

bug #65259: Don't say documentation for class itself comes from class constructor

Submitter:  Rik <rik5>
Submitted:  Mon 05 Feb 2024 11:03:48 PM UTC
   
 
Category:  Classdef Severity:  2 - Minor
Priority:  3 - Low Item Group:  Feature Request
Status:  Confirmed Assigned to:  None
Originator Name:  Open/Closed:  * Open
Release:  * dev Operating System:  * Any
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Tue 06 Feb 2024 05:07:23 PM UTC, comment #4: 

if we're looking at playing with the which command, we can of course see if any concerns of our current oldest bug #32088, specifically comments #6-11, are related. (that's specific to implementing the -all option to which, but it seems the solution is highly dependent on how which looks for subfns, methods, etc.)

Nicholas Jankowski <nrjank>
Group Member
Tue 06 Feb 2024 04:43:49 PM UTC, comment #3: 

This turns out to be pulling on a thread and having the whole sweater unravel.

I think there is something wrong with the way 'which' is operating on classdef files.

For starters, the function


  bool get_which_info_from_fcn (const std::string& name, const octave_value& ov_fcn, std::string& file, std::string& type) const;


is declared in help.h as a private method of the class help_system.  But using "hg grep" I can't find any other usage of this function outside of help.cc.

1) Wouldn't it be better to make get_which_info_from_fcn a static local function to help.cc?

The code path begins with


help_system::which (const std::string& name,
                    std::string& type) const


This function first looks for a '.' character to see if it has a whole function name, or a package/class prefix and a subsequent function name.


  size_t pos = name.find ('.');

  if (pos == std::string::npos)
    {
      // Simple name.  If not found, continue looking for packages and
      // classes.

      octave_value ov_fcn = symtab.find_function (name);

      if (get_which_info_from_fcn (name, ov_fcn, file, type))
        return file;
    }


What's interesting here is that a bare classname, such as "inputParser" runs through this code path completely missing the next section


  // NAME contains '.' and must match the following pattern:
  //
  //   (package.)*(package|classname).(property|method)*
  //
  // Start by looking up the full name.  It could be either a package or
  // a class and we are done.  Otherwise, strip the final component and
  // lookup that name.  If it is a package, look for a function.  If it
  // is a class, look for a property or method.

  cdef_manager& cdm = m_interpreter.get_cdef_manager ();

  // FIXME: In the following search we may load classes.  Is that really
  // what we want, or should we just search the loadpath for
  // +pkga/+pkgb/classname/file.m, etc. and attempt to extract help text
  // without actually installing packages and classes into the fcn_info
  // table?

  // Is NAME a class?

  cdef_class cls = cdm.find_class (name, false, true);

  if (cls.ok ())
    {
      // FIXME: Return documentation for the class or the class
      // constructor?

      file = cls.file_name ();
      type = "classdef class";

      return file;
    }

  cdef_package pkg = cdm.find_package (name, false, true);

  if (pkg.ok ())
    {
      // FIXME: How to get the fill name of a package?
      file = pkg.get_name ();
      type = "package";

      return file;
    }


As far as I can tell, this is dead code (well, not the package part).

It seems that either the simple code path should be avoided for a class name so that the dead code is activated, OR the code in get_which_info_from_fcn() should be modified to test for bare class name, OR is_classdef_constructor() should not return true when no input name is given.

Any thoughts, reasoning on which would be better?


Rik <rik5>
Group administrator
Tue 06 Feb 2024 12:07:55 AM UTC, comment #2: 

That first line comes from the code for the "which" command and is separate from the code that provides the rest of the help text.  There is some duplication and overlap in those functions that should probably be refactored.

John W. Eaton <jwe>
Group administrator
Mon 05 Feb 2024 11:06:31 PM UTC, comment #1: 

Just a note to say that any change will be in help.cc around line 255.


          if (fcn->is_classdef_meta ())
            {
              octave_classdef_meta *meta_obj
                = dynamic_cast<octave_classdef_meta *> (fcn);

              file = meta_obj->file_name ();

              if (meta_obj->is_classdef_constructor ())
                type = "class constructor";
              else if (meta_obj->is_classdef_method ())
                type = "class method";
              else
                type = "classdef meta object";
            }


Rik <rik5>
Group administrator
Mon 05 Feb 2024 11:03:48 PM UTC, original submission:  

This is a very small thing.  When asking for help on a class, Octave reports the help as coming from the "class constructor".  This is not necessarily true.  Documentation is allowed both for the class and for the constructor and they are not necessarily the same.  Here is an example with inputParser:


help inputParser
'inputParser' is a class constructor from the file /home/XXX/.../scripts/miscellaneous/inputParser.m


It would be nicer if it reported


help inputParser
'inputParser' is a class from the file /home/XXX/.../scripts/miscellaneous/inputParser.m


for the class and the original message only for the actual constructor accessed with "help inputParser.inputParser".

Rik <rik5>
Group administrator

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by nrjank (Posted a comment)
  • -email is unavailable- added by jwe (Posted a comment)
  • -email is unavailable- added by rik5 (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only group members can vote.

     

    Follows 1 latest change.

    Date Changed by Updated Field Previous Value => Replaced by
    2024-02-06 rik5 Priority5 - Normal 3 - Low

    Back to the top

    Powered by Savane 3.13-0329.
    Corresponding source code