# HG changeset patch
# User Rik <rik@octave.org>
# Date 1412115083 25200
# Node ID 23519ad614dae0e4f6b3f0fc6c671b51d5c7dcd5
# Parent  5b64aee2257b88732553fd2bf842d97554db9cbc
inputname.m: Overhaul function.

* inputname.m: Improve docstring.  Put input validation first.  Add BIST tests
for input validation.

* ov-usr-fcn.cc (Fnargin, Fnargout, Fisargout): Improve docstrings and
streamline seealso references.

diff -r 5b64aee2257b -r 23519ad614da libinterp/octave-value/ov-usr-fcn.cc
--- a/libinterp/octave-value/ov-usr-fcn.cc	Tue Sep 30 12:36:23 2014 -0700
+++ b/libinterp/octave-value/ov-usr-fcn.cc	Tue Sep 30 15:11:23 2014 -0700
@@ -832,9 +832,11 @@
        "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {} nargin ()\n\
 @deftypefnx {Built-in Function} {} nargin (@var{fcn})\n\
-Within a function, return the number of arguments passed to the function.\n\
-At the top level, return the number of command line arguments passed to\n\
-Octave.\n\
+Report the number of input arguments to a function.\n\
+\n\
+Called from within a function, return the number of arguments passed to the\n\
+function.  At the top level, return the number of command line arguments\n\
+passed to Octave.\n\
 \n\
 If called with the optional argument @var{fcn}---a function name or handle---\n\
 return the declared number of arguments that the function can accept.\n\
@@ -854,7 +856,7 @@
 @end example\n\
 \n\
 Programming Note: @code{nargin} does not work on built-in functions.\n\
-@seealso{nargout, varargin, isargout, varargout, nthargout}\n\
+@seealso{nargout, narginchk, varargin, inputname}\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -913,11 +915,18 @@
        "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {} nargout ()\n\
 @deftypefnx {Built-in Function} {} nargout (@var{fcn})\n\
-Within a function, return the number of values the caller expects to\n\
-receive.  If called with the optional argument @var{fcn}---a function\n\
-name or handle---return the number of declared output values that the\n\
-function can produce.  If the final output argument is @var{varargout}\n\
-the returned value is negative.\n\
+Report the number of output arguments from a function.\n\
+\n\
+Called from within a function, return the number of values the caller expects\n\
+to receive.  At the top level, @code{nargout} with no argument is undefined\n\
+and will produce an error.\n\
+\n\
+If called with the optional argument @var{fcn}---a function name or\n\
+handle---return the number of declared output values that the function can\n\
+produce.\n\
+\n\
+If the final output argument is @var{varargout} the returned value is\n\
+negative.\n\
 \n\
 For example,\n\
 \n\
@@ -952,10 +961,9 @@
 will return -2, because @code{imread} has two outputs and the second is\n\
 @var{varargout}.\n\
 \n\
-At the top level, @code{nargout} with no argument is undefined and will\n\
-produce an error.  @code{nargout} does not work for built-in functions and\n\
+Programming Note.  @code{nargout} does not work for built-in functions and\n\
 returns -1 for all anonymous functions.\n\
-@seealso{nargin, varargin, isargout, varargout, nthargout}\n\
+@seealso{nargin, varargout, isargout, nthargout}\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -1078,16 +1086,18 @@
        "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} isargout (@var{k})\n\
 Within a function, return a logical value indicating whether the argument\n\
-@var{k} will be assigned to a variable on output.  If the result is false,\n\
-the argument has been ignored during the function call through the use of\n\
-the tilde (~) special output argument.  Functions can use @code{isargout} to\n\
-avoid performing unnecessary calculations for outputs which are unwanted.\n\
+@var{k} will be assigned to a variable on output.\n\
+\n\
+If the result is false, the argument has been ignored during the function\n\
+call through the use of the tilde (~) special output argument.  Functions\n\
+can use @code{isargout} to avoid performing unnecessary calculations for\n\
+outputs which are unwanted.\n\
 \n\
 If @var{k} is outside the range @code{1:max (nargout)}, the function returns\n\
 false.  @var{k} can also be an array, in which case the function works\n\
 element-by-element and a logical array is returned.  At the top level,\n\
 @code{isargout} returns an error.\n\
-@seealso{nargout, nargin, varargin, varargout, nthargout}\n\
+@seealso{nargout, varargout, nthargout}\n\
 @end deftypefn")
 {
   octave_value retval;
diff -r 5b64aee2257b -r 23519ad614da scripts/miscellaneous/inputname.m
--- a/scripts/miscellaneous/inputname.m	Tue Sep 30 12:36:23 2014 -0700
+++ b/scripts/miscellaneous/inputname.m	Tue Sep 30 15:11:23 2014 -0700
@@ -22,22 +22,26 @@
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {} inputname (@var{n})
 ## Return the name of the @var{n}-th argument to the calling function.
+##
 ## If the argument is not a simple variable name, return an empty string.
+## @code{inputname} may only be used within a function body, not at the
+## command line.
+## @seealso{nargin, nthargout}
 ## @end deftypefn
 
 function s = inputname (n)
 
-  if (nargin == 1)
-    s = evalin ("caller", sprintf ("__varval__ (\".argn.\"){%d};", n));
-    ## For compatibility with Matlab, return empty string if argument
-    ## name is not a valid identifier.
-    if (! isvarname (s))
-      s = "";
-    endif
-  else
+  if (nargin != 1)
     print_usage ();
   endif
 
+  s = evalin ("caller", sprintf ("__varval__ (\".argn.\"){%d};", n));
+  ## For compatibility with Matlab,
+  ## return empty string if argument name is not a valid identifier.
+  if (! isvarname (s))
+    s = "";
+  endif
+
 endfunction
 
 
@@ -62,3 +66,7 @@
 %!endfunction
 %!assert (foo (pi, e), "e");
 %!assert (feval (@foo, pi, e), "e");
+
+%!error inputname ()
+%!error inputname (1,2)
+