bugGNU Octave - Bugs: bug #63782, "help myfunc" issues a...


bug #63782: "help myfunc" issues a warning if myfunc code has a problem

Submitter:  Hartmut <hardy>
Submitted:  Fri 10 Feb 2023 12:52:23 PM UTC
Category:  Octave Function Severity:  3 - Normal
Priority:  3 - Low Item Group:  Unexpected Error or Warning
Status:  Confirmed Assigned to:  None
Originator Name:  Open/Closed:  * Open
Release:  * stable Operating System:  * Any
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup

Sat 11 Feb 2023 05:43:59 PM UTC, comment #2: 

I know this issue has been reported before as well.

I think it would be nice to separate the documentation from parsing of the function, but as jwe notes this may not be trivial.  Given all the other items to tackle in Octave, I think this is pretty low priority.

Also, the workaround is pretty simple.  If there are errors or warnings then simply correct the code (which would need to happen anyways).

Rik <rik5>
Group administrator
Fri 10 Feb 2023 03:44:24 PM UTC, comment #1: 

I'm almost certain that this problem has been reported before but I can't find the bug report now.

It would be fine to change Octave's way of extracting docstrings from function files to avoid this behavior.

The current behavior happens because Octave finds the docstring and stores it along with the function definition when the function is parsed.  That was all implemented a long time ago and it seemed easiest to have the help function just try to load the named function and then return the docstring that was stored with the parsed function.  You don't see the warning the second time because the function doesn't need to be parsed again.  The docstring is already available from the internal table of functions.

Fixing this is not as easy as just grabbing the first block of comments from a file.  Individual classdef methods can have docstrings, so at least for those, you really may need to parse the entire file.  And we need to have the parser store help text for functions entered at the command line.  Maybe we could have the help function return the docstring from the function table if it is available and if not, invoke the parser in a special way so that it stops parsing once the docstring is found, suppresses diagnostic messages, and doesn't store the function definition (so diagnostic messages will be displayed when the code is actually parsed to be executed).

John W. Eaton <jwe>
Group administrator
Fri 10 Feb 2023 12:52:23 PM UTC, original submission:  

This behavior does not seem to be new, but it came as an unexpected suprprise to me, and I am not sure if it is intended behavior.

Here is how to reproduce the behavior:
1. generate a function m-file that as a code "problem" inside, e.g. this one:

## This is my doc string.
function myfunc
  if (1==1)
    disp ("hello")
    a = 1

2. save this function m-file under the corresponding filename, in this example myfunc.m
3. change the current folder to this file's folder.
4. now call "help" to display the help string of this m-file function.

observed result: (with any current Octave version like 8.0.90, 7.3.0, 6.4.0, ..., 4.2.2)

>> help myfunc
warning: suggest parenthesis around assignment used as truth value near line 6, column 7 in file 'C:\...\myfunc.m'
warning: called from
    help at line 103 column 20

This warning is very true in itself. I was just suprised that the "help" function displays it. There is no problem with the help string of this function, so shouldn't the help function just output this help string without any complaint?

Calling "help myfunc" afterwards for a second time, does NOT produce this warning any more.

Is this intended behavior? Or do we want to change this?

Hartmut <hardy>


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

Attach Files:

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 rik5 (Posted a comment)
  • -email is unavailable- added by jwe (Posted a comment)
  • -email is unavailable- added by hardy (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.


    Follow 2 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2023-02-11 rik5 Priority5 - Normal 3 - Low
        StatusNone Confirmed

    Back to the top

    Powered by Savane 3.13-ee12.
    Corresponding source code