[Octave-bug-tracker] [bug #51191] help text of first function in an Octave program uses wrong comment block

[Carnë Draug]

Follow-up Comment #3, bug #51191 (project octave):

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



    _______________________________________________________

Reply to this item at:

  <http://savannah.gnu.org/bugs/?51191>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.gnu.org/