[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Request for comments: help texts (was: Re: Inconsistent treatment of scr
From: |
John W. Eaton |
Subject: |
Request for comments: help texts (was: Re: Inconsistent treatment of scripts by the help system?) |
Date: |
Thu, 25 Feb 2010 10:53:37 -0500 |
On 25-Feb-2010, David Grundberg 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?
I think it would be simpler if the help function just displayed the
first non-copyright block of comments no matter where it appears in
the file. I don't really care that it might produce strange results
if someone doesn't have an actual docstring as the first comment in
the file, and I don't think it is worth doing a lot of work to try to
distinguish all these various cases.
jwe