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

 
 

bug #51191: help text of first function in an Octave script (not function) uses wrong comment block

Submitter:  Carnë Draug <carandraug>
Submitted:  Tue 06 Jun 2017 02:03:19 PM UTC
   
 
Category:  Interpreter Severity:  2 - Minor
Priority:  1 - Later Item Group:  Documentation
Status:  Confirmed Assigned to:  None
Originator Name:  Open/Closed:  * Open
Release:  * dev Operating System:  * GNU/Linux
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Mon 15 Jan 2024 04:38:42 AM UTC, comment #8: 

I know this bug is ancient, but I had someone run a compatibility test with Matlab.  See https://octave.discourse.group/t/request-for-matlab-compatibility-test/5184.

Octave is Matlab-compatible, in that both fail to pick up the documentation for the first function in a script file.  It's not great, but I'm lowering the priority since there are workarounds (every function in its own file, using functions and subfunctions, etc.).

Rik <rik5>
Group administrator
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>
Group 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>
Group 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>
Group 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>
Group 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:


$ cat octave-script
## This is is some comment at the top of the program.

## We need this package
pkg load signal;

## Define some variables
X = 1;
Y = 2;

## Documentation for foo
function x = foo (y)
  x = y+1;
endfunction

## Documentation for bar
function x = bar (y)
  x = y-1;
endfunction
$ octave-cli -q
octave-cli:1> suppress_verbose_help_message (1)
octave-cli:2> source "octave-script"
octave-cli:3> man foo
'foo' is a command-line function

 This is is some comment at the top of the program.

octave-cli:4> man bar
'bar' is a command-line function

 Documentation for bar


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:


$ octave-cli -q
octave-cli:1> suppress_verbose_help_message (1)
octave-cli:2> ## some comments
octave-cli:2> pkg load signal;
octave-cli:3> ## define some variables
octave-cli:3> X = 1;
octave-cli:4> Y = 2;
octave-cli:5> ## first line comments (note empty line next)
octave-cli:5>
octave-cli:5> ## documentation for foo
octave-cli:5> function x = foo (y), x = y+1; endfunction
octave-cli:6>
octave-cli:6> ## some more comments
octave-cli:6>
octave-cli:6> ## documentation for bar
octave-cli:6> function x = bar (y) x = y+1; endfunction
octave-cli:7> man foo
'foo' is a command-line function

 documentation for foo

octave-cli:8> man bar
'bar' is a command-line function

 documentation for bar


Carnë Draug <carandraug>
Group 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>
Group 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>
Group 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:



$ cat > an-octave-script << END
> #!/usr/bin/env octave
>
> ## This is the help text of the foo function.
> function x = foo (y, z)
>    x = y+z;
> endfunction
>
> ## This is the help text of the bar function.
> function x = bar (y, z)
>   x = y+z;
> endfunction
> END
carandraug@microna:~$ octave-cli -q
octave-cli:1> source ("an-octave-script")
octave-cli:2> help foo
'foo' is a command-line function

!/usr/bin/env octave

octave-cli:3> help bar
'bar' is a command-line function

 This is the help text of the bar function.


Carnë Draug <carandraug>
Group Member

 

(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 rik5 (Posted a comment)
  • -email is unavailable- added by carandraug (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 11 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2024-01-15 rik5 Severity3 - Normal 2 - Minor
        Priority5 - Normal 1 - Later
        StatusNeed Info Confirmed
        Summaryhelp text of first function in an Octave program uses wrong comment block help text of first function in an Octave script (not function) uses wrong comment block
    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.13-3230.
    Corresponding source code