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

Submitter:  Carnë Draug <carandraug>
Submitted:  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
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment (Rich Markup)
   

( 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>
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 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.11