--- a/scripts/miscellaneous/setfield.m
+++ b/scripts/miscellaneous/setfield.m
@@ -18,25 +18,80 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function File} {[@var{k1}, @dots{}, @var{v1}] =} setfield (@var{s}, @var{k1}, @var{v1}, @dots{})
-## Set a field member in a (nested) structure array.  For example:
+## @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})
+##
+## Set a field member @var{field} in a structure @var{s} equal to @var{val}.  For example:
 ##
 ## @example
 ## @group
-## oo(1,1).f0 = 1;
-## oo = setfield (oo, @{1,2@}, "fd", @{3@}, "b", 6);
-## oo(1,2).fd(3).b == 6
-##      @result{} ans = 1
+## @var{s} = struct ();
+## @var{s} = setfield (@var{s}, "foo bar", 42);
 ## @end group
 ## @end example
 ##
+## @noindent
+## This is equivalent to
+##
+## @example
+## @var{s}.("foo bar") = 42;
+## @end example
+##
+## @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{doc-warning_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.
+##
+## Thus consider instead,
+##
+## @example
+## @group
+## @var{s} = struct ("baz", 42);
+## setfield (@var{s}, @{1@}, "foo", @{1@}, "bar", 5)
+##     @result{} ans =
+##     scalar structure containing the fields:
+##       baz =  42
+##       foo =
+##         scalar structure containing the fields:
+##           bar =  54
+## @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.
+##
+## 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}(2).bar(3)
+##      @result{} ans =
+##      scalar structure containing the fields:
+##        baz =  6
+## @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
+##
 ## Note that the same result as in the above example could be achieved by:
 ##
 ## @example
 ## @group
-## i1 = @{1,2@}; i2 = "fd"; i3 = @{3@}; i4 = "b";
-## oo(i1@{:@}).(i2)(i3@{:@}).(i4) == 6
-##      @result{} ans = 1
+## @var{SA}.foo = 1;
+## @var{SA}(2).bar(3).baz = 6
 ## @end group
 ## @end example
 ## @seealso{getfield, rmfield, isfield, isstruct, fieldnames, struct}