bugGNU Octave - Bugs: bug #64065, help text in m-file incorrectly...


bug #64065: help text in m-file incorrectly identified

Submitter:  Rik <rik5>
Submitted:  Tue 18 Apr 2023 10:43:03 PM UTC
Category:  Interpreter Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Incorrect Result
Status:  Fixed Assigned to:  None
Originator Name:  Open/Closed:  * Closed
Release:  * dev Operating System:  * Any
Fixed Release:  9.1.0 (current default) Planned Release:  9.1.0 (current default)
* Mandatory Fields

Add a New Comment (Rich Markup)

Wed 31 May 2023 03:55:57 AM UTC, comment #2: 

Thanks to your detective work I found where in lex.ll to make a change.  In the end, I found a simple one-line solution which was to verify that the comment type was NOT "end_of_line" (versus "block" or "full_line") before adding the comment text as help text.  See changeset http://hg.savannah.gnu.org/hgweb/octave/rev/aaaee134c8df.

Marking bug as Fixed and closing report.

Rik <rik5>
Group administrator
Wed 24 May 2023 11:49:46 AM UTC, comment #1: 


I spent some time debugging octave to find the root-cause of this bug. This was my first foray into octave code, and was certainly a lot of fun.

The problem comes from the fact that the lexical parser distinguishes full line comments from end of line comments, but in the end puts both of them in the same category of LINE_COMMENT.

In the patch attached, if a comment line is an end of line comment, it is marked as such, as is not used as help_text for the function.

With this fcn_help.m provided by Rik

function r = fcn_help (x)
  r = x;   # Single-line comment, not documentation for function

calling print_usage() correctly detects that usage is not provided.

octave:> print_usage('fcn_help')
error: print_usage: 'fcn_help' is not documented

Now, if a line or two, of comments are added in the beginning of the function, that is correctly identified as the correct usage.

function r = fcn_help (x)
# how to use this function
  # this is how
  r = x;   # Single-line comment, not documentation for function

octave:1> print_usage('fcn_help')
error: Invalid call to fcn_help.  Correct usage is:

 how to use this function
 this is how

(file #54781)

Ali Zahraee <dexores>
Tue 18 Apr 2023 10:43:03 PM UTC, original submission:  

Consider the following function fcn_help.m

function r = fcn_help (x)
  r = x;   # Single-line comment, not documentation for function

Calling print_usage() incorrectly identifies the single-line comment as the documentation for the entire function.

print_usage ('fcn_help')
error: Invalid call to fcn_help.  Correct usage is:

 Single-line comment, not documentation for function

The problem can be traced further back to function get_help_text() in libinterp/corefcn/help.cc.

It seems to me that Octave should be checking for comments that take an entire line as being possible documentation, and not comments that are attached to a piece of code as this one is.

Rik <rik5>
Group administrator


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

Attach Files:

Attached Files
file #54781:  print_usage.fix.patch added by dexores (1KiB - text/plain)
file #54637:  fcn_help.m added by rik5 (103B - text/x-matlab)


Depends on the following items: None found

Items that depend on this one: None found


Carbon-Copy List
  • -email is unavailable- added by dexores (Updated the item)
  • -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 project members can vote.





    Follow 6 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2023-05-31 rik5 StatusConfirmed Fixed
        Open/ClosedOpen Closed
        Fixed ReleaseNone 9.1.0 (current default)
        Planned ReleaseNone 9.1.0 (current default)
    2023-05-24 dexores Attached File- Added print_usage.fix.patch, #54781
    2023-04-18 rik5 Attached File- Added fcn_help.m, #54637

    Back to the top

    Powered by Savane 3.12