--- a/libinterp/octave-value/ov-struct.cc	Tue Oct 21 09:39:03 2014 -0700
+++ b/libinterp/octave-value/ov-struct.cc	Tue Oct 21 09:57:02 2014 -0700
@@ -1814,7 +1814,7 @@
 \n\
 Finally, if the value is a non-scalar cell array, then @code{struct}\n\
 produces a struct @strong{array}.\n\
-@seealso{cell2struct, fieldnames, orderfields, getfield, setfield, rmfield, structfun}\n\
+@seealso{cell2struct, fieldnames, getfield, setfield, rmfield, isfield, orderfields, isstruct, structfun}\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -2012,8 +2012,10 @@
 @deftypefn  {Built-in Function} {} isfield (@var{x}, \"@var{name}\")\n\
 @deftypefnx {Built-in Function} {} isfield (@var{x}, @var{name})\n\
 Return true if the @var{x} is a structure and it includes an element named\n\
-@var{name}.  If @var{name} is a cell array of strings then a logical array of\n\
-equal dimension is returned.\n\
+@var{name}.\n\
+\n\
+If @var{name} is a cell array of strings then a logical array of equal\n\
+dimension is returned.\n\
 @seealso{fieldnames}\n\
 @end deftypefn")
 {
@@ -2237,12 +2239,14 @@
 
 DEFUN (rmfield, args, ,
        "-*- texinfo -*-\n\
-@deftypefn  {Built-in Function} {@var{s} =} rmfield (@var{s}, \"@var{f}\")\n\
-@deftypefnx {Built-in Function} {@var{s} =} rmfield (@var{s}, @var{f})\n\
+@deftypefn  {Built-in Function} {@var{sout} =} rmfield (@var{s}, \"@var{f}\")\n\
+@deftypefnx {Built-in Function} {@var{sout} =} rmfield (@var{s}, @var{f})\n\
 Return a @emph{copy} of the structure (array) @var{s} with the field @var{f}\n\
-removed.  If @var{f} is a cell array of strings or a character array, remove\n\
-each of the named fields.\n\
-@seealso{orderfields, fieldnames}\n\
+removed.\n\
+\n\
+If @var{f} is a cell array of strings or a character array, remove each of\n\
+the named fields.\n\
+@seealso{orderfields, fieldnames, isfield}\n\
 @end deftypefn")
 {
   octave_value retval;

--- a/scripts/miscellaneous/getfield.m	Tue Oct 21 09:39:03 2014 -0700
+++ b/scripts/miscellaneous/getfield.m	Tue Oct 21 09:57:02 2014 -0700
@@ -18,30 +18,38 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {[@var{val}] =} getfield (@var{s}, @var{field})
-## @deftypefnx {Function File} {[@var{val}] =} getfield (@var{s}, @var{idx1}, @var{field1}, @var{idx2}, @var{field2}, @dots{})
-## Extract a field from a structure (or a nested structure).  The syntax
-## is the same as @code{setfield}, except it omits the final @var{val}
-## argument, returning this value instead of setting it.
+## @deftypefn  {Function File} {@var{val} =} getfield (@var{s}, @var{field})
+## @deftypefnx {Function File} {@var{val} =} getfield (@var{s}, @var{sidx1}, @var{field1}, @var{fidx1}, @dots{})
+## Get the value of the field named @var{field} from a structure or nested
+## structure @var{s}.
 ##
-## @seealso{setfield, rmfield, isfield, fieldnames, isstruct, struct}
+## If @var{s} is a structure array then @var{sidx} selects an element of the
+## structure array, @var{field} specifies the field name of the selected
+## element, and @var{fidx} selects which element of the field (in the case of
+## an array or cell array).  See @code{setfield} for a more complete
+## description of the syntax.
+##
+## @seealso{setfield, rmfield, orderfields, isfield, fieldnames, isstruct, struct}
 ## @end deftypefn
 
 ## Author: Etienne Grossmann <etienne@cs.uky.edu>
 
-function obj = getfield (s, varargin)
+function val = getfield (s, varargin)
+
   if (nargin < 2)
     print_usage ();
   endif
+
   subs = varargin;
   flds = cellfun ("isclass", subs, "char");
   idxs = cellfun ("isclass", subs, "cell");
-  if (all (flds | idxs))
-    typs = merge (flds, {"."}, {"()"});
-    obj = subsref (s, struct ("type", typs, "subs", subs));
-  else
+  if (! all (flds | idxs))
     error ("getfield: invalid index");
   endif
+
+  typs = merge (flds, {"."}, {"()"});
+  val = subsref (s, struct ("type", typs, "subs", subs));
+
 endfunction
 
 
@@ -49,6 +57,11 @@
 %! x.a = "hello";
 %! assert (getfield (x, "a"), "hello");
 %!test
-%! ss(1,2).fd(3).b = 5;
-%! assert (getfield (ss,{1,2},"fd",{3},"b"), 5);
+%! ss(1,2).fd(3).b(1,4) = 5;
+%! assert (getfield (ss,{1,2},"fd",{3},"b", {1,4}), 5);
 
+%% Test input validation
+%!error getfield ()
+%!error getfield (1)
+%!error <invalid index> getfield (1,2)
+

--- a/scripts/miscellaneous/orderfields.m	Tue Oct 21 09:39:03 2014 -0700
+++ b/scripts/miscellaneous/orderfields.m	Tue Oct 21 09:57:02 2014 -0700
@@ -17,20 +17,23 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {[@var{t}, @var{p}] =} orderfields (@var{s1})
-## @deftypefnx {Function File} {[@var{t}, @var{p}] =} orderfields (@var{s1}, @var{s2})
-## Return a copy of @var{s1} with fields arranged alphabetically or as
-## specified by @var{s2}.
-##
-## Given one struct, arrange field names in @var{s1} alphabetically.
+## @deftypefn  {Function File} {@var{sout}] =} orderfields (@var{s1})
+## @deftypefnx {Function File} {@var{sout}] =} orderfields (@var{s1}, @var{s2})
+## @deftypefnx {Function File} {@var{sout}] =} orderfields (@var{s1}, @{@var{cellstr}@})
+## @deftypefnx {Function File} {@var{sout}] =} orderfields (@var{s1}, @var{p})
+## @deftypefnx {Function File} {[@var{sout}, @var{p}] =} orderfields (@dots{})
+## Return a @emph{copy} of @var{s1} with fields arranged alphabetically, or as
+## specified by the second input.
 ##
-## If the second argument is a struct, arrange field names in @var{s1} as they
+## Given one input struct @var{s1}, arrange field names alphabetically.
+##
+## If a second struct argument is given, arrange field names in @var{s1} as they
 ## appear in @var{s2}.  The second argument may also specify the order in a
-## permutation vector or a cell array of strings containing the fieldnames of
-## @var{s1} in the desired order.
+## cell array of strings @var{cellstr}.  The second argument may also be a
+## permutation vector. 
 ##
-## The optional second output argument @var{p} is assigned the permutation
-## vector which converts the original name order into the new name order.
+## The optional second output argument @var{p} is the permutation vector which
+## converts the original name order to the new name order.
 ##
 ## Examples:
 ##
@@ -84,20 +87,18 @@
 ## @end group
 ## @end example
 ##
-## @seealso{getfield, rmfield, isfield, isstruct, fieldnames, struct}
+## @seealso{fieldnames, getfield, setfield, rmfield, isfield, isstruct, struct}
 ## @end deftypefn
 
 ## Author: Paul Kienzle <pkienzle@users.sf.net>
 ## Adapted-By: jwe
 
-function [t, p] = orderfields (s1, s2)
+function [sout, p] = orderfields (s1, s2)
 
-  if (nargin == 1 || nargin == 2)
-    if (! isstruct (s1))
-      error ("orderfields: S1 must be a struct");
-    endif
-  else
+  if (nargin < 1 || nargin > 2)
     print_usage ();
+  elseif (! isstruct (s1))
+    error ("orderfields: S1 must be a struct");
   endif
 
   if (nargin == 1)
@@ -110,32 +111,34 @@
       ## Two structures: return the fields in the order of s2.
       names = fieldnames (s2);
       if (! isequal (sort (fieldnames (s1)), sort (names)))
-        error ("orderfields: structures do not have the same fields");
+        error ("orderfields: structures S1 and S2 do not have the same fields");
       endif
     elseif (iscellstr (s2))
       ## A structure and a list of fields: order by the list of fields.
       t1 = sort (fieldnames (s1));
       t2 = sort (s2(:));
       if (! isequal (t1, t2))
-        error ("orderfields: name list does not match structure fields");
+        error ("orderfields: CELLSTR list does not match structure fields");
       endif
       names = s2;
     elseif (isvector (s2))
       ## A structure and a permutation vector: permute the order of s1.
       names = fieldnames (s1);
-      t1 = sort (s2);
-      t1 = t1(:)';
-      t2 = 1:numel (names);
+      t1 = 1:numel (names);
+      t2 = sort (s2);
+      t2 = t2(:)';
       if (! isequal (t1, t2))
-        error ("orderfields: invalid permutation vector");
+        error ("orderfields: invalid permutation vector P");
       endif
       names = names(s2);
+    else
+      error ("orderfields: second argument must be structure, cellstr, or permutation vector");
     endif
   endif
 
   ## Corner case of empty struct
   if (isempty (names))
-    t = struct ();
+    sout = struct ();
     p = [];
   endif
 
@@ -150,19 +153,22 @@
   endif
 
   ## Permute the names in the structure.
-  if (numel (s1) == 0)
+  if (isempty (s1))
+    ## Corner case of empty structure.  Still need to re-order fields.
     args = cell (1, 2 * numel (names));
     args(1:2:end) = names;
     args(2:2:end) = {[]};
-    t = struct (args{:});
+    sout = struct (args{:});
+    ## inherit dimensions
+    sout = resize (sout, size (s1));
   else
     n = numel (s1);
     for i = 1:numel (names)
       el = names{i};
-      [t(1:n).(el)] = s1(:).(el);
+      [sout(1:n).(el)] = s1(:).(el);
     endfor
     ## inherit dimensions
-    t = reshape (t, size (s1));
+    sout = reshape (sout, size (s1));
   endif
 
 endfunction
@@ -202,4 +208,28 @@
 
 ## Corner case of empty struct, bug #40224
 %!assert (orderfields (struct ()), struct ())
+%!test
+%! s(2,2).a = 1;
+%! s(1,1).b = 2;
+%! s = resize (s, [1 0]);
+%! s2 = orderfields (s, {"b", "a"});
+%! assert (fieldnames (s2), {"b"; "a"});
+%! assert (size_equal (s, s2));
 
+## Test input validation
+%!error orderfields ()
+%!error orderfields (1,2,3)
+%!error <S1 must be a struct> orderfields (1)
+%!error <S1 and S2 do not have the same fields>
+%! s1.a = 1;
+%! s2.b = 2;
+%! orderfields (s1, s2);
+%!error <CELLSTR list does not match structure fields>
+%! s1.a = 1;
+%! orderfields (s1, {"b"});
+%!error <invalid permutation vector P>
+%! s1.a = 1;
+%! orderfields (s1, [2 1]);
+%!error <second argument must be structure, cellstr, or permutation vector>
+%! s1.a = 1;
+%! orderfields (s1, ones (2,2));

--- a/scripts/miscellaneous/setfield.m	Tue Oct 21 09:39:03 2014 -0700
+++ b/scripts/miscellaneous/setfield.m	Tue Oct 21 09:57:02 2014 -0700
@@ -18,10 +18,12 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} {@var{s} =} setfield (@var{s}, @var{field}, @var{val})
-## @deftypefnx {Function File} {@var{s} =} setfield (@var{s}, @var{idx1}, @var{field1}, @var{idx2}, @var{field2}, @dots{}, @var{val})
+## @deftypefn  {Function File} {@var{sout} =} setfield (@var{s}, @var{field}, @var{val})
+## @deftypefnx {Function File} {@var{sout} =} setfield (@var{s}, @var{sidx1}, @var{field1}, @var{fidx1}, @var{sidx2}, @var{field2}, @var{fidx2}, @dots{}, @var{val})
 ##
-## Set a field member @var{field} in a structure @var{s} equal to @var{val}. 
+## Return a @emph{copy} of the structure @var{s} with the field member
+## @var{field} set to the value @var{val}. 
+##
 ## For example:
 ##
 ## @example
@@ -40,24 +42,29 @@
 ##
 ## @noindent
 ## Note that ordinary structure syntax @code{@var{s}.foo bar = 42} cannot be
-## used here, as the field name is not a valid Octave identifier.  Using
-## arbitrary strings for field name is incompatible with @sc{matlab}, so
-## this usage will warn if the @code{Octave:matlab-incompatible} warning
-## is set.  @xref{XREFwarning_ids}.
+## used here, as the field name is not a valid Octave identifier because of
+## the space character.  Using arbitrary strings for field names is
+## incompatible with @sc{matlab}, and this usage will emit a warning if the
+## warning ID @code{Octave:matlab-incompatible} is enabled.
+## @xref{XREFwarning_ids}.
 ##
-## With the second calling form, set a field on a structure array,
-## possibly nested, with successive nested indices @var{idx1},
-## @var{idx2}, @dots{} and fields @var{field1}, @var{field2}, @dots{}
-## The indices must be cells containing the desired index at this
-## nesting depth.
+## With the second calling form, set a field of a structure array.  The
+## input @var{sidx} selects an element of the structure array, @var{field}
+## specifies the field name of the selected element, and @var{fidx} selects
+## which element of the field (in the case of an array or cell array).
+## The @var{sidx}, @var{field}, and @var{fidx} inputs can be repeated to
+## address nested structure array elements.  The structure array index and
+## field element index must be cell arrays while the field name must be a
+## string.
 ##
-## Thus consider instead,
+## For example:
 ##
 ## @example
 ## @group
 ## @var{s} = struct ("baz", 42);
-## setfield (@var{s}, @{1@}, "foo", @{1@}, "bar", 5)
-##     @result{} ans =
+## setfield (@var{s}, @{1@}, "foo", @{1@}, "bar", 54)
+## @result{}
+##   ans =
 ##     scalar structure containing the fields:
 ##       baz =  42
 ##       foo =
@@ -66,54 +73,61 @@
 ## @end group
 ## @end example
 ##
-## Here we first have an ordinary structure array with one field
-## @code{baz} set to 42.  Then we set another field in a nested scalar structure
-## indexing with two single cells containing the unique desired indices.
+## The example begins with an ordinary scalar structure to which a nested 
+## scalar structure is added.  In all cases, if the structure index @var{sidx}
+## is not specified it defaults to 1 (scalar structure).  Thus, the example
+## above could be written more concisely as
+## @code{setfield (@var{s}, "foo", "bar", 54)}
 ##
-## Finally an example with nested structure arrays,
+## Finally, an example with nested structure arrays:
 ##
 ## @example
 ## @group
 ## @var{sa}.foo = 1;
-## @var{sa} = setfield (@var{sa}, @{2@}, "bar", @{3@}, "baz", 6);
+## @var{sa} = setfield (@var{sa}, @{2@}, "bar", @{3@}, "baz", @{1, 4@}, 5);
 ## @var{sa}(2).bar(3)
-##      @result{} ans =
-##      scalar structure containing the fields:
-##        baz =  6
+## @result{}
+##   ans =
+##     scalar structure containing the fields:
+##       baz =  0   0   0   5
 ## @end group
 ## @end example
 ##
-## Here @var{sa} is a structure array whose field @code{fd} at elements
-## 1 and 2 field is in turn
-## another structure array whose third element is a structure
+## Here @var{sa} is a structure array whose field at elements 1 and 2 is in
+## turn another structure array whose third element is a simple scalar
+## structure.  The terminal scalar structure has a field which contains a
+## matrix value.
 ##
 ## Note that the same result as in the above example could be achieved by:
 ##
 ## @example
 ## @group
-## @var{SA}.foo = 1;
-## @var{SA}(2).bar(3).baz = 6
+## @var{sa}.foo = 1;
+## @var{sa}(2).bar(3).baz(1,4) = 5
 ## @end group
 ## @end example
-## @seealso{getfield, rmfield, isfield, fieldnames, isstruct, struct}
+## @seealso{getfield, rmfield, orderfields, isfield, fieldnames, isstruct, struct}
 ## @end deftypefn
 
 ## Author:  Etienne Grossmann <etienne@cs.uky.edu>
 
-function obj = setfield (obj, varargin)
+function sout = setfield (s, varargin)
+
   if (nargin < 3)
     print_usage ();
   endif
+
   subs = varargin(1:end-1);
-  rhs = varargin{end};
+  val = varargin{end};
   flds = cellfun ("isclass", subs, "char");
   idxs = cellfun ("isclass", subs, "cell");
-  if (all (flds | idxs))
-    typs = merge (flds, {"."}, {"()"});
-    obj = subsasgn (obj, struct ("type", typs, "subs", subs), rhs);
-  else
+  if (! all (flds | idxs))
     error ("setfield: invalid index");
   endif
+
+  typs = ifelse (flds, {"."}, {"()"});
+  sout = subsasgn (s, struct ("type", typs, "subs", subs), val);
+
 endfunction
 
 
@@ -121,9 +135,15 @@
 %! x.a = "hello";
 %! x = setfield (x, "b", "world");
 %! y = struct ("a", "hello", "b", "world");
-%! assert (x,y);
+%! assert (x, y);
 %!test
 %! oo(1,1).f0 = 1;
-%! oo = setfield (oo,{1,2},"fd",{3},"b", 6);
-%! assert (oo(1,2).fd(3).b, 6);
+%! oo = setfield (oo,{1,2},"fd",{3},"b", {1,4}, 6);
+%! assert (oo(1,2).fd(3).b(1,4), 6);
 
+%% Test input validation
+%!error setfield ()
+%!error setfield (1)
+%!error setfield (1,2)
+%!error <invalid index> setfield (1,2,3)
+