# HG changeset patch
# User Rik <rik@octave.org>
# Date 1412175103 25200
# Node ID 09bc8304f18259e9f0113d2547144a07ef70d6fc
# Parent  93f7f4d074b17ff4efbb55ddf1d0fd7f9d3d2527
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.

diff -r 93f7f4d074b1 -r 09bc8304f182 scripts/help/help.m
--- 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!_")
 
diff -r 93f7f4d074b1 -r 09bc8304f182 scripts/miscellaneous/info.m
--- 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)