Mercurial > octave-nkf
changeset 19231:09bc8304f182
doc: Improvements to help() and info() docstrings.
* help.m: Put 1-line summary of function first in docstring. Clarify
why one needs to use 'help comma' to get help on ',' operator.
Use list as a more meaningful variable name than tmp. Add more BIST
tests.
* info.m: Improve wording describing Octave Wiki in docstring.
| author | Rik <rik@octave.org> |
|---|---|
| date | Wed, 01 Oct 2014 07:51:43 -0700 |
| parents | 93f7f4d074b1 |
| children | 931cc13a6f3b |
| files | scripts/help/help.m scripts/miscellaneous/info.m |
| diffstat | 2 files changed, 25 insertions(+), 16 deletions(-) [+] |
line wrap: on
line diff
--- a/scripts/help/help.m Tue Sep 30 15:23:59 2014 -0700 +++ b/scripts/help/help.m Wed Oct 01 07:51:43 2014 -0700 @@ -20,9 +20,11 @@ ## @deftypefn {Command} {} help @var{name} ## @deftypefnx {Command} {} help @code{--list} ## @deftypefnx {Command} {} help @code{.} -## Display the help text for @var{name}. For example, the command -## @kbd{help help} prints a short message describing the @code{help} -## command. +## @deftypefnx {Command} {} help +## Display the help text for @var{name}. +## +## For example, the command @kbd{help help} prints a short message describing +## the @code{help} command. ## ## Given the single argument @code{--list}, list all operators, ## keywords, built-in functions, and loadable functions available @@ -34,10 +36,11 @@ ## If invoked without any arguments, @code{help} display instructions ## on how to access help from the command line. ## -## The help command can give you information about operators, but not the -## comma and semicolons that are used as command separators. To get help -## for those, you must type @kbd{help comma} or @kbd{help semicolon}. -## @seealso{doc, lookfor, which} +## The help command can provide information about most operators, for example +## @code{help +}, but not the comma and semicolon characters which are used +## by the Octave interpreter as command separators. For help on either of +## these type @kbd{help comma} or @kbd{help semicolon}. +## @seealso{doc, lookfor, which, info} ## @end deftypefn function retval = help (name) @@ -69,21 +72,21 @@ elseif (nargin == 1 && ischar (name)) if (strcmp (name, "--list")) - tmp = do_list_functions (); + list = do_list_functions (); if (nargout == 0) - printf ("%s", tmp); + printf ("%s", list); else - retval = tmp; + retval = list; endif return; endif if (strcmp (name, ".")) - tmp = do_list_operators (); + list = do_list_operators (); if (nargout == 0) - printf ("%s", tmp); + printf ("%s", list); else - retval = tmp; + retval = list; endif return; endif @@ -129,7 +132,7 @@ function retval = do_list_operators () retval = sprintf ("*** operators:\n\n%s\n\n", - list_in_columns (__operators__ ())); + list_in_columns (__operators__ ())); endfunction function retval = do_list_functions () @@ -207,5 +210,10 @@ %!assert (! isempty (strfind (help ("ls"), "List directory contents"))) +%!assert (! isempty (strfind (help ("."), "||"))) + +## Test input validation %!error <invalid input> help (42) +%!error <invalid input> help ("abc", "def") +%!error <'_!UNLIKELY_FCN!_' not found> help ("_!UNLIKELY_FCN!_")
--- a/scripts/miscellaneous/info.m Tue Sep 30 15:23:59 2014 -0700 +++ b/scripts/miscellaneous/info.m Wed Oct 01 07:51:43 2014 -0700 @@ -31,7 +31,8 @@ Octave are available at\n\ http://www.octave.org/support.html\n\ \n\ - You may also find some information in the Octave Wiki at\n\ + The Octave Wiki has user-generated content on a variety of subjects\n\ + including installation and is available at\n\ http://wiki.octave.org\n\ \n\ Additional functionality can be enabled by using packages from\n\ @@ -46,6 +47,6 @@ endfunction -## Mark file as being tested. No real test needed for this function. +## Mark file as being tested. No real test needed for a documentation .m file %! assert (1)