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 Jun 6 14:03:19 2017  
Category: InterpreterSeverity: 3 - Normal
Priority: 5 - NormalItem Group: Documentation
Status: Need InfoAssigned to: None
Originator Name: Open/Closed: Open
Release: devOperating System: GNU/Linux

Add a New Comment (Rich MarkupRich Markup):

You are not logged in

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


(Jump to the original submission Jump to the original submission)

Fri Jun 16 15:31:07 2017, 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 Jun 16 12:01:22 2017, 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 Jun 15 23:16:39 2017, comment #5:

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

Rik <rik5>
Project Administrator
Wed Jun 7 23:33:49 2017, 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 Jun 7 23:17:22 2017, 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 Jun 7 19:12:34 2017, 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 Jun 6 20:14:58 2017, 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 Jun 6 14:03:19 2017, 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 File(s):

No files currently attached


Depends on the following items: None found

Items that depend on this one: None found


Carbon-Copy List
  • -unavailable- added by rik5 (Posted a comment)
  • -unavailable- added by carandraug (Submitted the item)

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

    Only project members can vote.


    Please enter the title of George Orwell's famous dystopian book (it's a date):



    Follow 7 latest changes.

    Date Changed By Updated Field Previous Value => Replaced By
    Wed Jun 7 23:34:11 2017rik5Open/ClosedClosed=>Open
    Wed Jun 7 23:33:49 2017rik5StatusFixed=>Need Info
    Wed Jun 7 19:12:34 2017rik5StatusConfirmed=>Fixed
    Tue Jun 6 20:14:58 2017rik5Item GroupNone=>Documentation
    Tue Jun 6 14:03:35 2017carandraugSummaryhelp 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.1-cleanup1