On Thu, Feb 25, 2010 at 3:57 PM, David Grundberg
<address@hidden> wrote:
Olaf Till wrote:
If the command "help ..." is called on a script (not a function), I
would expect that one either always gets "... is not documented" or,
if present, the first comment in the script is displayed. The current
behavior is not so, seemingly function definitions within the script
have an unwanted effect.
I'm moving this to the maintainer list.
I can do the needed changes but I think we need to agree on the
semantics.
For example a file with the sole contents (indented to be easier
to read):
## Optional copyright block
## help for script
## other comment
is a clear. The help filename should give "help for script".
Notice that copyright blocks should be skipped. Yes, it's
tricky.
This however:
## Optional copyright block
1;
## help for script
function f ()
endfunction
Here I think 'help filename' should be undocumented, because
there is a statement before it.
Function declarations inside script files: Theoretically we could
make 'help f' return "help for f", but I don't think it is worth
supporting. Therefore:
help filename: undocumented
help f: undocumented
Script file with function declarations:
## Optional copyright block
## help for script
## other comment
1;
## help for f
function f ()
endfunction
In short:
help filename: "help for script"
help f: undocumented
Summary: To document a script file, write your help text
block (optionally with a copyright block before it) before the
first statement. All following comment blocks are ignored.
Really simple rule. Help text for function declarations inside
scripts are ignored.
And function files:
## Copyright block
## help for primary function
## ignored comment
function myfunction ()
endfunction
## help for subfunction
function sub ()
endfunction
help filename: "help for primary function"
help sub: No such function
There is no way to access sub, so it can't be described by help.
There is one other kind of help text inside function files:
function myfunction ()
% Help text inside function.
% other comment.
end
This kind of 'stuck-inside' help text is very common in
non-Octave contexts. I think it's ugly and sends the wrong kind
of signals. But it's common and people do need the help text,
therefore:
help filename: "Help text inside function".
What do you think of this? Is it OK? Does it break existing
files? How would this affect !demo and !test blocks?
David