bugGNU Octave - Bugs: bug #51191, help text of first function in an...


bug #51191: help text of first function in an Octave program uses wrong comment block

Submitted by:  Carnë Draug <carandraug>
Submitted on:  Tue 06 Jun 2017 02:03:19 PM UTC  
Category:  Interpreter Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Documentation
Status:  Need Info Assigned to:  None
Originator Name:  Open/Closed:  Open
Release:  dev Operating System:  GNU/Linux

Add a New Comment(Rich Markup)

You are not logged in

Please log in, so followups can be emailed to you.


( Jump to the original submission)

Fri 16 Jun 2017 03:31:07 PM UTC, comment #7:

@Carnë: You and I are the only ones on the CC list for this bug. Do you want to put a request out on the Octave-Maintainers or Octave-Help list with the trial code? There is almost always someone willing to cut and paste into Matlab and return the results.

Rik <rik5>
Project Administrator
Fri 16 Jun 2017 12:01:22 PM UTC, comment #6:

In function files, I believe Matlab uses the first block of comments which usually comes after the function definition line (we do the first or second). But this bug is about functions defined in a script.

Matlab did not allow functions defined in a script file, I think they only implemented that in 2016b so whoever checks it will need to have a recent Matlab version.

The thing is that this works fine when done at the Octave prompt, a function help text is the comment before the function definition, and I always assumed that source would have the same behaviour as copy paste at the prompt.

Carnë Draug <carandraug>
Project Member
Thu 15 Jun 2017 11:16:39 PM UTC, comment #5:

Ping! Any chance to run the test script on Matlab to see how it handles this?

Rik <rik5>
Project Administrator
Wed 07 Jun 2017 11:33:49 PM UTC, comment #4:

What does Matlab do for the example script in comment #3?

It was my understanding that they just ripped the first comment block out of the file and used it for documentation. I thought Octave was copying that behavior with the one exception that Copyright statements--more common to GPL Octave code than to Matlab codes--were excluded.

If the desire is actually to find the first comment block immediately preceding a function declaration then the changes will be more significant.

Rik <rik5>
Project Administrator
Wed 07 Jun 2017 11:17:22 PM UTC, comment #3:

The problem was not specific of a shebang line, picking up the first block of comments for the function help text. This is fine for function files, not so much for scripts that were sourced. And this affects the first function only:

I experimented with having multiple blocks of comments between functions and seems that in such case, the help text for a function is the first block of comments since the last endfunction (I guess reading the parser would be more effective than experimenting). But because usually functions definitions are usually one after the other, that is not an issue there.

When running things in the actual interpreter, it seems to pick the last block of comments before the function definition which would make more sense:

Carnë Draug <carandraug>
Project Member
Wed 07 Jun 2017 07:12:34 PM UTC, comment #2:

I fixed the issue in this cset (http://hg.savannah.gnu.org/hgweb/octave/rev/9151922777e2). Closing report.

Rik <rik5>
Project Administrator
Tue 06 Jun 2017 08:14:58 PM UTC, comment #1:

Confirmed. Octave is picking up the the shebang line instead of the help text. As a minor point, executable Octave scripts like this are typically used in batch mode and there isn't a reason to call help on them. Still, it would be good to fix this.

Rik <rik5>
Project Administrator
Tue 06 Jun 2017 02:03:19 PM UTC, original submission:

An Octave program can have multiple functions defined with their own help text which help will be able to pick up. However, it seems that the first function help text is the first block comments which in the case of a program will be the shebang line. See:

Carnë Draug <carandraug>
Project Member


(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 carandraug (Submitted the item)

    Do you think this task is very important?
    If so, you can add your encouragement to it.
    This task has 0 encouragements so far.

    Only project members can vote.




    Follow 7 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2017-06-07 rik5 Open/ClosedClosed => Open
    2017-06-07 rik5 StatusFixed => Need Info
    2017-06-07 rik5 StatusConfirmed => Fixed
        Open/ClosedOpen => Closed
    2017-06-06 rik5 Item GroupNone => Documentation
        StatusNone => Confirmed
    2017-06-06 carandraug Summaryhelp text of first function in an Octave program uses wrongly comment => help text of first function in an Octave program uses wrong comment block

    Back to the top

    Powered by Savane 3.4