# HG changeset patch
# User Rik <rik@octave.org>
# Date 1411850517 25200
# Node ID 1faae07afbd8e01934abde27237883ef9f8da60c
# Parent  9163a6e9b09631c4eed76aef23883a45e541ec15
Overhaul givens and planerot functions.

* givens.cc (Fgivens): Redo docstring.  Remove useless default to detect
nargout > 2 in switch statements.

* planerot.m: Redo docstring.  Add input validation.  Add BIST tests for input validation.

diff -r 9163a6e9b096 -r 1faae07afbd8 libinterp/corefcn/givens.cc
--- a/libinterp/corefcn/givens.cc	Sat Sep 27 12:47:37 2014 -0700
+++ b/libinterp/corefcn/givens.cc	Sat Sep 27 13:41:57 2014 -0700
@@ -32,10 +32,12 @@
 
 DEFUN (givens, args, nargout,
        "-*- texinfo -*-\n\
-@deftypefn  {Built-in Function} {@var{g} =} givens (@var{x}, @var{y})\n\
+@deftypefn  {Built-in Function} {@var{G} =} givens (@var{x}, @var{y})\n\
 @deftypefnx {Built-in Function} {[@var{c}, @var{s}] =} givens (@var{x}, @var{y})\n\
+Compute the Givens rotation matrix @var{G}.\n\
+\n\
 @tex\n\
-Return a $2\\times 2$ orthogonal matrix\n\
+The Givens matrix is a $2\\times 2$ orthogonal matrix\n\
 $$\n\
  G = \\left[\\matrix{c & s\\cr -s'& c\\cr}\\right]\n\
 $$\n\
@@ -46,11 +48,20 @@
 with $x$ and $y$ scalars.\n\
 @end tex\n\
 @ifnottex\n\
-Return a 2 by 2 orthogonal matrix\n\
-@code{@var{g} = [@var{c} @var{s}; -@var{s}' @var{c}]} such that\n\
-@code{@var{g} [@var{x}; @var{y}] = [*; 0]} with @var{x} and @var{y} scalars.\n\
+The Givens matrix is a 2 by 2 orthogonal matrix\n\
+\n\
+@code{@var{g} = [@var{c} @var{s}; -@var{s}' @var{c}]}\n\
+\n\
+such that\n\
+\n\
+@code{@var{g} [@var{x}; @var{y}] = [*; 0]}\n\
+\n\
+with @var{x} and @var{y} scalars.\n\
 @end ifnottex\n\
 \n\
+If two output arguments are requested, return the factors @var{c} and\n\
+@var{s} rather than the Givens rotation matrix.\n\
+\n\
 For example:\n\
 \n\
 @example\n\
@@ -60,6 +71,7 @@
        -0.70711   0.70711\n\
 @end group\n\
 @end example\n\
+@seealso{planerot}\n\
 @end deftypefn")
 {
   octave_value_list retval;
@@ -97,10 +109,6 @@
                           retval(1) = result (0, 1);
                           retval(0) = result (0, 0);
                           break;
-
-                        default:
-                          error ("givens: invalid number of output arguments");
-                          break;
                         }
                     }
                 }
@@ -127,10 +135,6 @@
                           retval(1) = result (0, 1);
                           retval(0) = result (0, 0);
                           break;
-
-                        default:
-                          error ("givens: invalid number of output arguments");
-                          break;
                         }
                     }
                 }
@@ -160,10 +164,6 @@
                           retval(1) = result (0, 1);
                           retval(0) = result (0, 0);
                           break;
-
-                        default:
-                          error ("givens: invalid number of output arguments");
-                          break;
                         }
                     }
                 }
@@ -190,10 +190,6 @@
                           retval(1) = result (0, 1);
                           retval(0) = result (0, 0);
                           break;
-
-                        default:
-                          error ("givens: invalid number of output arguments");
-                          break;
                         }
                     }
                 }
@@ -211,4 +207,5 @@
 
 %!error givens ()
 %!error givens (1)
+%!error [a,b,c] = givens (1, 1)
 */
diff -r 9163a6e9b096 -r 1faae07afbd8 scripts/linear-algebra/planerot.m
--- a/scripts/linear-algebra/planerot.m	Sat Sep 27 12:47:37 2014 -0700
+++ b/scripts/linear-algebra/planerot.m	Sat Sep 27 13:41:57 2014 -0700
@@ -17,8 +17,8 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function File} {[@var{g}, @var{y}] =} planerot (@var{x})
-## Given a two-element column vector, returns the
+## @deftypefn {Function File} {[@var{G}, @var{y}] =} planerot (@var{x})
+## Given a two-element column vector, return the
 ## @tex
 ## $2 \times 2$ orthogonal matrix
 ## @end tex
@@ -31,8 +31,16 @@
 ## @end deftypefn
 
 function [G, y] = planerot (x)
+
+  if (nargin != 1)
+    print_usage ();
+  elseif (! (isvector (x) && numel (x) == 2))
+    error ("planerot: X must be a 2-element vector");
+  endif
+
   G = givens (x(1), x(2));
   y = G * x(:);
+
 endfunction
 
 
@@ -42,7 +50,8 @@
 %! assert (g, [x(1) x(2); -x(2) x(1)] / sqrt (x(1)^2 + x(2)^2), 2e-8);
 %! assert (y(2), 0, 2e-8);
 
-%!error planerot ([0])
-%!error planerot ([0 0 0])
 %!error planerot ()
+%!error planerot (1,2)
+%!error <X must be a 2-element vector> planerot (ones (2,2))
+%!error <X must be a 2-element vector> planerot ([0 0 0])