--- a/libinterp/corefcn/sparse.cc	Wed Apr 05 18:11:52 2023 +0200
+++ b/libinterp/corefcn/sparse.cc	Thu Apr 06 12:13:26 2023 -0700
@@ -80,44 +80,62 @@
 
 DEFUN (sparse, args, ,
        doc: /* -*- texinfo -*-
-@deftypefn  {} {@var{s} =} sparse (@var{a})
-@deftypefnx {} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n})
-@deftypefnx {} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv})
-@deftypefnx {} {@var{s} =} sparse (@var{m}, @var{n})
-@deftypefnx {} {@var{s} =} sparse (@var{i}, @var{j}, @var{s}, @var{m}, @var{n}, "unique")
-@deftypefnx {} {@var{s} =} sparse (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n}, @var{nzmax})
-Create a sparse matrix from a full matrix, or row, column, value triplets.
+@deftypefn  {} {@var{S} =} sparse (@var{A})
+@deftypefnx {} {@var{S} =} sparse (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n})
+@deftypefnx {} {@var{S} =} sparse (@var{i}, @var{j}, @var{sv})
+@deftypefnx {} {@var{S} =} sparse (@var{m}, @var{n})
+@deftypefnx {} {@var{S} =} sparse (@var{i}, @var{j}, @var{s}, @var{m}, @var{n}, "unique")
+@deftypefnx {} {@var{S} =} sparse (@var{i}, @var{j}, @var{sv}, @var{m}, @var{n}, @var{nzmax})
+Create a sparse matrix from a full matrix @var{A} or row, column, value
+triplets.
 
-If @var{a} is a full matrix, convert it to a sparse matrix representation,
-removing all zero values in the process.
+If @var{A} is a full matrix, convert it to a sparse matrix representation,
+removing all zero values in the process.  The matrix @var{A} should be of type
+logical or double.
 
 Given the integer index vectors @var{i} and @var{j}, and a 1-by-@code{nnz}
 vector of real or complex values @var{sv}, construct the sparse matrix
 @code{S(@var{i}(@var{k}),@var{j}(@var{k})) = @var{sv}(@var{k})} with overall
-dimensions @var{m} and @var{n}.  If any of @var{sv}, @var{i} or @var{j} are
+dimensions @var{m} and @var{n}.  If any of @var{i}, @var{j}, or @var{sv} are
 scalars, they are expanded to have a common size.
 
-If @var{m} or @var{n} are not specified their values are derived from the
+If @var{m} or @var{n} are not specified then their values are derived from the
 maximum index in the vectors @var{i} and @var{j} as given by
-@code{@var{m} = max (@var{i})}, @code{@var{n} = max (@var{j})}.
+@w{@code{@var{m} = max (@var{i})}}, @w{@code{@var{n} = max (@var{j})}}.
 
-@strong{Note}: if multiple values are specified with the same @var{i},
-@var{j} indices, the corresponding value in @var{s} will be the sum of the
+@strong{Note}: If multiple values are specified with the same @var{i},
+@var{j} indices, the corresponding value in @var{S} will be the sum of the
 values at the repeated location.  @xref{XREFaccumarray,,@code{accumarray}}, for
 an example of how to produce different behavior such as taking the minimum
 instead.
 
-If the option @qcode{"unique"} is given, and more than one value is
-specified at the same @var{i}, @var{j} indices, then the last specified
-value will be used.
+If the option @qcode{"unique"} is given, and more than one value is specified
+at the same @var{i}, @var{j} indices, then only the last specified value will
+be used.
 
 @code{sparse (@var{m}, @var{n})} will create an empty @var{m}x@var{n} sparse
 matrix and is equivalent to @code{sparse ([], [], [], @var{m}, @var{n})}
 
-The argument @var{nzmax} is ignored but accepted for compatibility with
-@sc{matlab}.
+The optional final argument reserves space for @var{nzmax} values in the sparse
+array and is useful if the eventual number of nonzero values will be greater
+than the number of values in @var{sv} used during the initial construction of
+the array.  @xref{XREFspalloc,,@code{spalloc}}, for more information and usage
+instructions.
+
+Example 1 (convert full matrix to sparse to save memory):
 
-Example 1 (sum at repeated indices):
+@example
+@group
+x = full (diag (1:1000));
+sizeof (x)
+@result{}  8000000
+s = sparse (x);
+sizeof (xs)
+@result{}  24008
+@end group
+@end example
+
+Example 2 (sum at repeated indices):
 
 @example
 @group
@@ -131,7 +149,7 @@
 @end group
 @end example
 
-Example 2 ("unique" option):
+Example 3 ("unique" option):
 
 @example
 @group