octave-nkf: libinterp/corefcn/data.cc comparison

comparison libinterp/corefcn/data.cc @ 20207:4f45eaf83908 stable

doc: Update more docstrings to have one sentence summary as first line. Reviewed libinterp/corefcn directory. * libinterp/corefcn/__ilu__.cc, libinterp/corefcn/balance.cc, libinterp/corefcn/besselj.cc, libinterp/corefcn/betainc.cc, libinterp/corefcn/bitfcns.cc, libinterp/corefcn/bsxfun.cc, libinterp/corefcn/cellfun.cc, libinterp/corefcn/colloc.cc, libinterp/corefcn/conv2.cc, libinterp/corefcn/data.cc, libinterp/corefcn/debug.cc, libinterp/corefcn/defaults.cc, libinterp/corefcn/det.cc, libinterp/corefcn/dirfns.cc, libinterp/corefcn/dlmread.cc, libinterp/corefcn/dot.cc, libinterp/corefcn/eig.cc, libinterp/corefcn/error.cc, libinterp/corefcn/fft2.cc, libinterp/corefcn/fftn.cc, libinterp/corefcn/file-io.cc, libinterp/corefcn/filter.cc, libinterp/corefcn/find.cc, libinterp/corefcn/gammainc.cc, libinterp/corefcn/gcd.cc, libinterp/corefcn/getgrent.cc, libinterp/corefcn/getpwent.cc, libinterp/corefcn/getrusage.cc, libinterp/corefcn/graphics.cc, libinterp/corefcn/help.cc, libinterp/corefcn/hex2num.cc, libinterp/corefcn/input.cc, libinterp/corefcn/inv.cc, libinterp/corefcn/kron.cc, libinterp/corefcn/load-path.cc, libinterp/corefcn/load-save.cc, libinterp/corefcn/lookup.cc, libinterp/corefcn/ls-oct-ascii.cc, libinterp/corefcn/lsode.cc, libinterp/corefcn/lu.cc, libinterp/corefcn/luinc.cc, libinterp/corefcn/mappers.cc, libinterp/corefcn/matrix_type.cc, libinterp/corefcn/max.cc, libinterp/corefcn/md5sum.cc, libinterp/corefcn/mgorth.cc, libinterp/corefcn/nproc.cc, libinterp/corefcn/oct-hist.cc, libinterp/corefcn/ordschur.cc, libinterp/corefcn/pager.cc, libinterp/corefcn/pinv.cc, libinterp/corefcn/pr-output.cc, libinterp/corefcn/pt-jit.cc, libinterp/corefcn/quad.cc, libinterp/corefcn/quadcc.cc, libinterp/corefcn/qz.cc, libinterp/corefcn/rand.cc, libinterp/corefcn/rcond.cc, libinterp/corefcn/regexp.cc, libinterp/corefcn/schur.cc, libinterp/corefcn/sighandlers.cc, libinterp/corefcn/sparse.cc, libinterp/corefcn/spparms.cc, libinterp/corefcn/str2double.cc, libinterp/corefcn/strfind.cc, libinterp/corefcn/strfns.cc, libinterp/corefcn/sub2ind.cc, libinterp/corefcn/svd.cc, libinterp/corefcn/symtab.cc, libinterp/corefcn/syscalls.cc, libinterp/corefcn/sysdep.cc, libinterp/corefcn/time.cc, libinterp/corefcn/toplev.cc, libinterp/corefcn/tril.cc, libinterp/corefcn/tsearch.cc, libinterp/corefcn/typecast.cc, libinterp/corefcn/urlwrite.cc, libinterp/corefcn/utils.cc, libinterp/corefcn/variables.cc, scripts/polynomial/spline.m: Update more docstrings to have one sentence summary as first line.

author	Rik <rik@octave.org>
date	Sat, 09 May 2015 17:19:30 -0700
parents	19755f4fc851
children	4e7f12a763cd

comparison

equal deleted inserted replaced

-:b70f8da6dcd3
+:4f45eaf83908
 DEFUN (atan2, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Mapping Function} {} atan2 (@var{y}, @var{x})\n\
 Compute atan (@var{y} / @var{x}) for corresponding elements of @var{y}\n\
-and @var{x}.  Signal an error if @var{y} and @var{x} do not match in size\n\
+and @var{x}.\n\
-and orientation.\n\
+\n\
+@var{y} and @var{x} must match in size and orientation.\n\
 @seealso{tan, tand, tanh, atanh}\n\
 @end deftypefn")
 {
 octave_value retval;
 DEFUN (hypot, args, ,
 "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {} hypot (@var{x}, @var{y})\n\
 @deftypefnx {Built-in Function} {} hypot (@var{x}, @var{y}, @var{z}, @dots{})\n\
 Compute the element-by-element square root of the sum of the squares of\n\
-@var{x} and @var{y}.  This is equivalent to\n\
+@var{x} and @var{y}.\n\
-@code{sqrt (@var{x}.^2 + @var{y}.^2)}, but calculated in a manner that\n\
+\n\
+This is equivalent to\n\
+@code{sqrt (@var{x}.^2 + @var{y}.^2)}, but is calculated in a manner that\n\
 avoids overflows for large values of @var{x} or @var{y}.\n\
+\n\
 @code{hypot} can also be called with more than 2 arguments; in this case,\n\
 the arguments are accumulated from left to right:\n\
 \n\
 @example\n\
 @group\n\
 */
 DEFUN (rem, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Mapping Function} {} rem (@var{x}, @var{y})\n\
-Return the remainder of the division @code{@var{x} / @var{y}}, computed\n\
+Return the remainder of the division @code{@var{x} / @var{y}}.\n\
-using the expression\n\
+\n\
+The remainder is computed using the expression\n\
 \n\
 @example\n\
 x - y .* fix (x ./ y)\n\
 @end example\n\
 \n\
-An error message is printed if the dimensions of the arguments do not\n\
+An error message is printed if the dimensions of the arguments do not agree,\n\
-agree, or if either of the arguments is complex.\n\
+or if either of the arguments is complex.\n\
 @seealso{mod}\n\
 @end deftypefn")
 {
 octave_value retval;
 */
 DEFUN (mod, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Mapping Function} {} mod (@var{x}, @var{y})\n\
-Compute the modulo of @var{x} and @var{y}.  Conceptually this is given by\n\
+Compute the modulo of @var{x} and @var{y}.\n\
+\n\
+Conceptually this is given by\n\
 \n\
 @example\n\
 x - y .* floor (x ./ y)\n\
 @end example\n\
 \n\
 @noindent\n\
-and is written such that the correct modulus is returned for\n\
+and is written such that the correct modulus is returned for integer types.\n\
-integer types.  This function handles negative values correctly.  That\n\
+This function handles negative values correctly.  That is,\n\
-is, @code{mod (-1, 3)} is 2, not -1, as @code{rem (-1, 3)} returns.\n\
+@code{mod (-1, 3)} is 2, not -1, as @code{rem (-1, 3)} returns.\n\
 @code{mod (@var{x}, 0)} returns @var{x}.\n\
 \n\
 An error results if the dimensions of the arguments do not agree, or if\n\
 either of the arguments is complex.\n\
 @seealso{rem}\n\
 DEFUN (cumprod, args, ,
 "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {} cumprod (@var{x})\n\
 @deftypefnx {Built-in Function} {} cumprod (@var{x}, @var{dim})\n\
-Cumulative product of elements along dimension @var{dim}.  If\n\
+Cumulative product of elements along dimension @var{dim}.\n\
-@var{dim} is omitted, it defaults to the first non-singleton dimension.\n\
+\n\
-\n\
+If @var{dim} is omitted, it defaults to the first non-singleton dimension.\n\
 @seealso{prod, cumsum}\n\
 @end deftypefn")
 {
 DATA_REDUCTION (cumprod);
 }
 @deftypefn  {Built-in Function} {} cumsum (@var{x})\n\
 @deftypefnx {Built-in Function} {} cumsum (@var{x}, @var{dim})\n\
 @deftypefnx {Built-in Function} {} cumsum (@dots{}, \"native\")\n\
 @deftypefnx {Built-in Function} {} cumsum (@dots{}, \"double\")\n\
 @deftypefnx {Built-in Function} {} cumsum (@dots{}, \"extra\")\n\
-Cumulative sum of elements along dimension @var{dim}.  If @var{dim}\n\
+Cumulative sum of elements along dimension @var{dim}.\n\
-is omitted, it defaults to the first non-singleton dimension.\n\
+\n\
+If @var{dim} is omitted, it defaults to the first non-singleton dimension.\n\
 \n\
 See @code{sum} for an explanation of the optional parameters\n\
 @qcode{\"native\"}, @qcode{\"double\"}, and @qcode{\"extra\"}.\n\
 @seealso{sum, cumprod}\n\
 @end deftypefn")
 @deftypefn  {Built-in Function} {@var{M} =} diag (@var{v})\n\
 @deftypefnx {Built-in Function} {@var{M} =} diag (@var{v}, @var{k})\n\
 @deftypefnx {Built-in Function} {@var{M} =} diag (@var{v}, @var{m}, @var{n})\n\
 @deftypefnx {Built-in Function} {@var{v} =} diag (@var{M})\n\
 @deftypefnx {Built-in Function} {@var{v} =} diag (@var{M}, @var{k})\n\
-Return a diagonal matrix with vector @var{v} on diagonal @var{k}.  The\n\
+Return a diagonal matrix with vector @var{v} on diagonal @var{k}.\n\
-second argument is optional.  If it is positive, the vector is placed on\n\
+\n\
+The second argument is optional.  If it is positive, the vector is placed on\n\
 the @var{k}-th superdiagonal.  If it is negative, it is placed on the\n\
-@var{-k}-th subdiagonal.  The default value of @var{k} is 0, and the\n\
+@var{-k}-th subdiagonal.  The default value of @var{k} is 0, and the vector\n\
-vector is placed on the main diagonal.  For example:\n\
+is placed on the main diagonal.  For example:\n\
 \n\
 @example\n\
 @group\n\
 diag ([1, 2, 3], 1)\n\
 @result{}  0  1  0  0\n\
 DEFUN (permute, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} permute (@var{A}, @var{perm})\n\
 Return the generalized transpose for an N-D array object @var{A}.\n\
+\n\
 The permutation vector @var{perm} must contain the elements\n\
 @code{1:ndims (A)} (in any order, but each element must appear only once).\n\
 \n\
-The @var{N}th dimension of @var{A} gets remapped to dimension \n\
+The @var{N}th dimension of @var{A} gets remapped to dimension\n\
 @code{@var{PERM}(@var{N})}.  For example:\n\
 \n\
 @example\n\
 @group\n\
 @var{x} = zeros ([2, 3, 5, 7]);\n\
 }
 DEFUN (ipermute, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} ipermute (@var{A}, @var{iperm})\n\
-The inverse of the @code{permute} function.  The expression\n\
+The inverse of the @code{permute} function.\n\
+\n\
+The expression\n\
 \n\
 @example\n\
 ipermute (permute (A, perm), perm)\n\
 @end example\n\
 \n\
 DEFUN (ndims, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} ndims (@var{a})\n\
 Return the number of dimensions of @var{a}.\n\
-For any array, the result will always be larger than or equal to 2.\n\
+\n\
+For any array, the result will always be greater than or equal to 2.\n\
 Trailing singleton dimensions are not counted.\n\
 \n\
 @example\n\
 @group\n\
 ndims (ones (4, 1, 2, 1))\n\
 DEFUN (numel, args, ,
 "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {} numel (@var{a})\n\
 @deftypefnx {Built-in Function} {} numel (@var{a}, @var{idx1}, @var{idx2}, @dots{})\n\
 Return the number of elements in the object @var{a}.\n\
+\n\
 Optionally, if indices @var{idx1}, @var{idx2}, @dots{} are supplied,\n\
 return the number of elements that would result from the indexing\n\
 \n\
 @example\n\
 @var{a}(@var{idx1}, @var{idx2}, @dots{})\n\
 DEFUN (size_equal, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} size_equal (@var{a}, @var{b}, @dots{})\n\
 Return true if the dimensions of all arguments agree.\n\
+\n\
 Trailing singleton dimensions are ignored.\n\
-Called with a single or no argument, size_equal returns true.\n\
+When called with a single or no argument @code{size_equal} returns true.\n\
 @seealso{size, numel, ndims}\n\
 @end deftypefn")
 {
 octave_value retval;
 DEFUN (sumsq, args, ,
 "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {} sumsq (@var{x})\n\
 @deftypefnx {Built-in Function} {} sumsq (@var{x}, @var{dim})\n\
-Sum of squares of elements along dimension @var{dim}.  If @var{dim}\n\
+Sum of squares of elements along dimension @var{dim}.\n\
-is omitted, it defaults to the first non-singleton dimension.\n\
+\n\
+If @var{dim} is omitted, it defaults to the first non-singleton dimension.\n\
 \n\
 This function is conceptually equivalent to computing\n\
 \n\
 @example\n\
 sum (x .* conj (x), dim)\n\
 DEFUN (isinteger, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} isinteger (@var{x})\n\
 Return true if @var{x} is an integer object (int8, uint8, int16, etc.).\n\
+\n\
 Note that @w{@code{isinteger (14)}} is false because numeric constants in\n\
 Octave are double precision floating point values.\n\
 @seealso{isfloat, ischar, islogical, isnumeric, isa}\n\
 @end deftypefn")
 {
 DEFUN (isfloat, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} isfloat (@var{x})\n\
 Return true if @var{x} is a floating-point numeric object.\n\
+\n\
 Objects of class double or single are floating-point objects.\n\
 @seealso{isinteger, ischar, islogical, isnumeric, isa}\n\
 @end deftypefn")
 {
 octave_value retval;
 DEFUN (complex, args, ,
 "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {} complex (@var{x})\n\
 @deftypefnx {Built-in Function} {} complex (@var{re}, @var{im})\n\
-Return a complex result from real arguments.  With 1 real argument @var{x},\n\
+Return a complex value from real arguments.\n\
-return the complex result @code{@var{x} + 0i}.  With 2 real arguments,\n\
+\n\
-return the complex result @code{@var{re} + @var{im}}.  @code{complex} can\n\
+With 1 real argument @var{x}, return the complex result @code{@var{x} + 0i}.\n\
-often be more convenient than expressions such as @code{a + i*b}.\n\
+\n\
+With 2 real arguments, return the complex result @code{@var{re} + @var{im}}.\n\
+@code{complex} can often be more convenient than expressions such as\n\
+@code{a + i*b}.\n\
 For example:\n\
 \n\
 @example\n\
 @group\n\
 complex ([1, 2], [3, 4])\n\
 DEFUN (isreal, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} isreal (@var{x})\n\
 Return true if @var{x} is a non-complex matrix or scalar.\n\
+\n\
 For compatibility with @sc{matlab}, this includes logical and character\n\
 matrices.\n\
 @seealso{iscomplex, isnumeric, isa}\n\
 @end deftypefn")
 {
 DEFUN (isempty, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} isempty (@var{a})\n\
 Return true if @var{a} is an empty matrix (any one of its dimensions is\n\
-zero).  Otherwise, return false.\n\
+zero).\n\
 @seealso{isnull, isa}\n\
 @end deftypefn")
 {
 octave_value retval = false;
 DEFUN (isnumeric, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} isnumeric (@var{x})\n\
 Return true if @var{x} is a numeric object, i.e., an integer, real, or\n\
-complex array.  Logical and character arrays are not considered to be\n\
+complex array.\n\
-numeric.\n\
+\n\
+Logical and character arrays are not considered to be numeric.\n\
 @seealso{isinteger, isfloat, isreal, iscomplex, islogical, ischar, iscell, isstruct, isa}\n\
 @end deftypefn")
 {
 octave_value retval;
 @deftypefnx {Built-in Function} {} ones (@var{m}, @var{n})\n\
 @deftypefnx {Built-in Function} {} ones (@var{m}, @var{n}, @var{k}, @dots{})\n\
 @deftypefnx {Built-in Function} {} ones ([@var{m} @var{n} @dots{}])\n\
 @deftypefnx {Built-in Function} {} ones (@dots{}, @var{class})\n\
 Return a matrix or N-dimensional array whose elements are all 1.\n\
+\n\
 If invoked with a single scalar integer argument @var{n}, return a square\n\
-@nospell{NxN} matrix.  If invoked with two or more scalar\n\
+@nospell{NxN} matrix.\n\
-integer arguments, or a vector of integer values, return an array with\n\
+\n\
-the given dimensions.\n\
+If invoked with two or more scalar integer arguments, or a vector of integer\n\
-\n\
+values, return an array with the given dimensions.\n\
-If you need to create a matrix whose values are all the same, you should\n\
+\n\
-use an expression like\n\
+To create a constant matrix whose values are all the same use an expression\n\
+such as\n\
 \n\
 @example\n\
 val_matrix = val * ones (m, n)\n\
 @end example\n\
 \n\
 @deftypefnx {Built-in Function} {} zeros (@var{m}, @var{n})\n\
 @deftypefnx {Built-in Function} {} zeros (@var{m}, @var{n}, @var{k}, @dots{})\n\
 @deftypefnx {Built-in Function} {} zeros ([@var{m} @var{n} @dots{}])\n\
 @deftypefnx {Built-in Function} {} zeros (@dots{}, @var{class})\n\
 Return a matrix or N-dimensional array whose elements are all 0.\n\
+\n\
 If invoked with a single scalar integer argument, return a square\n\
-@nospell{NxN} matrix.  If invoked with two or more scalar\n\
+@nospell{NxN} matrix.\n\
-integer arguments, or a vector of integer values, return an array with\n\
+\n\
-the given dimensions.\n\
+If invoked with two or more scalar integer arguments, or a vector of integer\n\
+values, return an array with the given dimensions.\n\
 \n\
 The optional argument @var{class} specifies the class of the return array\n\
 and defaults to double.  For example:\n\
 \n\
 @example\n\
 @result{} Inf   Inf\n\
 @end group\n\
 @end example\n\
 \n\
 When called with no arguments, return a scalar with the value @samp{Inf}.\n\
+\n\
 When called with a single argument, return a square matrix with the dimension\n\
-specified.  When called with more than one scalar argument the first two\n\
+specified.\n\
-arguments are taken as the number of rows and columns and any further\n\
+\n\
-arguments specify additional matrix dimensions.\n\
+When called with more than one scalar argument the first two arguments are\n\
+taken as the number of rows and columns and any further arguments specify\n\
+additional matrix dimensions.\n\
+\n\
 The optional argument @var{class} specifies the return type and may be\n\
 either @qcode{\"double\"} or @qcode{\"single\"}.\n\
 @seealso{isinf, NaN}\n\
 @end deftypefn")
 {
 @deftypefnx {Built-in Function} {} NaN (@var{n}, @var{m})\n\
 @deftypefnx {Built-in Function} {} NaN (@var{n}, @var{m}, @var{k}, @dots{})\n\
 @deftypefnx {Built-in Function} {} NaN (@dots{}, @var{class})\n\
 Return a scalar, matrix, or N-dimensional array whose elements are all equal\n\
 to the IEEE symbol NaN (Not a Number).\n\
+\n\
 NaN is the result of operations which do not produce a well defined numerical\n\
 result.  Common operations which produce a NaN are arithmetic with infinity\n\
 @tex\n\
 ($\\infty - \\infty$), zero divided by zero ($0/0$),\n\
 @end tex\n\
 (Inf - Inf), zero divided by zero (0/0),\n\
 @end ifnottex\n\
 and any operation involving another NaN value (5 + NaN).\n\
 \n\
 Note that NaN always compares not equal to NaN (NaN != NaN).  This behavior\n\
-is specified by the IEEE standard for floating point arithmetic.  To\n\
+is specified by the IEEE standard for floating point arithmetic.  To find\n\
-find NaN values, use the @code{isnan} function.\n\
+NaN values, use the @code{isnan} function.\n\
 \n\
 When called with no arguments, return a scalar with the value @samp{NaN}.\n\
+\n\
 When called with a single argument, return a square matrix with the dimension\n\
-specified.  When called with more than one scalar argument the first two\n\
+specified.\n\
-arguments are taken as the number of rows and columns and any further\n\
+\n\
-arguments specify additional matrix dimensions.\n\
+When called with more than one scalar argument the first two arguments are\n\
+taken as the number of rows and columns and any further arguments specify\n\
+additional matrix dimensions.\n\
+\n\
+\n\
 The optional argument @var{class} specifies the return type and may be\n\
 either @qcode{\"double\"} or @qcode{\"single\"}.\n\
 @seealso{isnan, Inf}\n\
 @end deftypefn")
 {
 @deftypefnx {Built-in Function} {} e (@var{n})\n\
 @deftypefnx {Built-in Function} {} e (@var{n}, @var{m})\n\
 @deftypefnx {Built-in Function} {} e (@var{n}, @var{m}, @var{k}, @dots{})\n\
 @deftypefnx {Built-in Function} {} e (@dots{}, @var{class})\n\
 Return a scalar, matrix, or N-dimensional array whose elements are all equal\n\
-to the base of natural logarithms.  The constant\n\
+to the base of natural logarithms.\n\
+\n\
+The constant\n\
 @tex\n\
 $e$ satisfies the equation $\\log (e) = 1$.\n\
 @end tex\n\
 @ifnottex\n\
 @samp{e} satisfies the equation @code{log} (e) = 1.\n\
 @end ifnottex\n\
 \n\
-When called with no arguments, return a scalar with the value @math{e}.  When\n\
+When called with no arguments, return a scalar with the value @math{e}.\n\
-called with a single argument, return a square matrix with the dimension\n\
+\n\
-specified.  When called with more than one scalar argument the first two\n\
+When called with a single argument, return a square matrix with the dimension\n\
-arguments are taken as the number of rows and columns and any further\n\
+specified.\n\
-arguments specify additional matrix dimensions.\n\
+\n\
+When called with more than one scalar argument the first two arguments are\n\
+taken as the number of rows and columns and any further arguments specify\n\
+additional matrix dimensions.\n\
+\n\
 The optional argument @var{class} specifies the return type and may be\n\
 either @qcode{\"double\"} or @qcode{\"single\"}.\n\
 @seealso{log, exp, pi, I}\n\
 @end deftypefn")
 {
 @deftypefnx {Built-in Function} {} eps (@var{x})\n\
 @deftypefnx {Built-in Function} {} eps (@var{n}, @var{m})\n\
 @deftypefnx {Built-in Function} {} eps (@var{n}, @var{m}, @var{k}, @dots{})\n\
 @deftypefnx {Built-in Function} {} eps (@dots{}, @var{class})\n\
 Return a scalar, matrix or N-dimensional array whose elements are all eps,\n\
-the machine precision.  More precisely, @code{eps} is the relative spacing\n\
+the machine precision.\n\
-between any two adjacent numbers in the machine's floating point system.\n\
+\n\
-This number is obviously system dependent.  On machines that support IEEE\n\
+More precisely, @code{eps} is the relative spacing between any two adjacent\n\
-floating point arithmetic, @code{eps} is approximately\n\
+numbers in the machine's floating point system.  This number is obviously\n\
+system dependent.  On machines that support IEEE floating point arithmetic,\n\
+@code{eps} is approximately\n\
 @tex\n\
 $2.2204\\times10^{-16}$ for double precision and $1.1921\\times10^{-7}$\n\
 @end tex\n\
 @ifnottex\n\
 2.2204e-16 for double precision and 1.1921e-07\n\
 @end ifnottex\n\
 for single precision.\n\
 \n\
 When called with no arguments, return a scalar with the value\n\
 @code{eps (1.0)}.\n\
-Given a single argument @var{x}, return the distance between @var{x} and\n\
+\n\
-the next largest value.\n\
+Given a single argument @var{x}, return the distance between @var{x} and the\n\
+next largest value.\n\
+\n\
 When called with more than one argument the first two arguments are taken as\n\
-the number of rows and columns and any further\n\
+the number of rows and columns and any further arguments specify additional\n\
-arguments specify additional matrix dimensions.\n\
+matrix dimensions.  The optional argument @var{class} specifies the return\n\
-The optional argument @var{class} specifies the return type and may be\n\
+type and may be either @qcode{\"double\"} or @qcode{\"single\"}.\n\
-either @qcode{\"double\"} or @qcode{\"single\"}.\n\
 @seealso{realmax, realmin, intmax, bitmax}\n\
 @end deftypefn")
 {
 int nargin = args.length ();
 octave_value retval;
 diameter($\\pi$).\n\
 @end tex\n\
 @ifnottex\n\
 diameter.\n\
 @end ifnottex\n\
+\n\
 Internally, @code{pi} is computed as @samp{4.0 * atan (1.0)}.\n\
 \n\
 When called with no arguments, return a scalar with the value of\n\
 @tex\n\
 $\\pi$.\n\
 @end tex\n\
 @ifnottex\n\
 pi.\n\
 @end ifnottex\n\
+\n\
 When called with a single argument, return a square matrix with the dimension\n\
-specified.  When called with more than one scalar argument the first two\n\
+specified.\n\
-arguments are taken as the number of rows and columns and any further\n\
+\n\
-arguments specify additional matrix dimensions.\n\
+When called with more than one scalar argument the first two arguments are\n\
+taken as the number of rows and columns and any further arguments specify\n\
+additional matrix dimensions.\n\
+\n\
 The optional argument @var{class} specifies the return type and may be\n\
 either @qcode{\"double\"} or @qcode{\"single\"}.\n\
 @seealso{e, I}\n\
 @end deftypefn")
 {
 @deftypefn  {Built-in Function} {} realmax\n\
 @deftypefnx {Built-in Function} {} realmax (@var{n})\n\
 @deftypefnx {Built-in Function} {} realmax (@var{n}, @var{m})\n\
 @deftypefnx {Built-in Function} {} realmax (@var{n}, @var{m}, @var{k}, @dots{})\n\
 @deftypefnx {Built-in Function} {} realmax (@dots{}, @var{class})\n\
-Return a scalar, matrix or N-dimensional array whose elements are all equal\n\
+Return a scalar, matrix, or N-dimensional array whose elements are all equal\n\
-to the largest floating point number that is representable.  The actual\n\
+to the largest floating point number that is representable.\n\
-value is system dependent.  On machines that support IEEE\n\
+\n\
+The actual value is system dependent.  On machines that support IEEE\n\
 floating point arithmetic, @code{realmax} is approximately\n\
 @tex\n\
 $1.7977\\times10^{308}$ for double precision and $3.4028\\times10^{38}$\n\
 @end tex\n\
 @ifnottex\n\
 @end ifnottex\n\
 for single precision.\n\
 \n\
 When called with no arguments, return a scalar with the value\n\
 @code{realmax (@qcode{\"double\"})}.\n\
+\n\
 When called with a single argument, return a square matrix with the dimension\n\
-specified.  When called with more than one scalar argument the first two\n\
+specified.\n\
-arguments are taken as the number of rows and columns and any further\n\
+\n\
-arguments specify additional matrix dimensions.\n\
+When called with more than one scalar argument the first two arguments are\n\
+taken as the number of rows and columns and any further arguments specify\n\
+additional matrix dimensions.\n\
+\n\
 The optional argument @var{class} specifies the return type and may be\n\
 either @qcode{\"double\"} or @qcode{\"single\"}.\n\
 @seealso{realmin, intmax, bitmax, eps}\n\
 @end deftypefn")
 {
 @deftypefn  {Built-in Function} {} realmin\n\
 @deftypefnx {Built-in Function} {} realmin (@var{n})\n\
 @deftypefnx {Built-in Function} {} realmin (@var{n}, @var{m})\n\
 @deftypefnx {Built-in Function} {} realmin (@var{n}, @var{m}, @var{k}, @dots{})\n\
 @deftypefnx {Built-in Function} {} realmin (@dots{}, @var{class})\n\
-Return a scalar, matrix or N-dimensional array whose elements are all equal\n\
+Return a scalar, matrix, or N-dimensional array whose elements are all equal\n\
 to the smallest normalized floating point number that is representable.\n\
+\n\
 The actual value is system dependent.  On machines that support\n\
 IEEE floating point arithmetic, @code{realmin} is approximately\n\
 @tex\n\
 $2.2251\\times10^{-308}$ for double precision and $1.1755\\times10^{-38}$\n\
 @end tex\n\
 @end ifnottex\n\
 for single precision.\n\
 \n\
 When called with no arguments, return a scalar with the value\n\
 @code{realmin (@qcode{\"double\"})}.\n\
+\n\
 When called with a single argument, return a square matrix with the dimension\n\
-specified.  When called with more than one scalar argument the first two\n\
+specified.\n\
-arguments are taken as the number of rows and columns and any further\n\
+\n\
-arguments specify additional matrix dimensions.\n\
+When called with more than one scalar argument the first two arguments are\n\
+taken as the number of rows and columns and any further arguments specify\n\
+additional matrix dimensions.\n\
+\n\
 The optional argument @var{class} specifies the return type and may be\n\
 either @qcode{\"double\"} or @qcode{\"single\"}.\n\
 @seealso{realmax, intmin, eps}\n\
 @end deftypefn")
 {
 @end ifnottex\n\
 \n\
 I, and its equivalents i, j, and J, are functions so any of the names may\n\
 be reused for other purposes (such as i for a counter variable).\n\
 \n\
-When called with no arguments, return a scalar with the value @math{i}.  When\n\
+When called with no arguments, return a scalar with the value @math{i}.\n\
-called with a single argument, return a square matrix with the dimension\n\
+\n\
-specified.  When called with more than one scalar argument the first two\n\
+When called with a single argument, return a square matrix with the dimension\n\
-arguments are taken as the number of rows and columns and any further\n\
+specified.\n\
-arguments specify additional matrix dimensions.\n\
+\n\
+When called with more than one scalar argument the first two arguments are\n\
+taken as the number of rows and columns and any further arguments specify\n\
+additional matrix dimensions.\n\
+\n\
 The optional argument @var{class} specifies the return type and may be\n\
 either @qcode{\"double\"} or @qcode{\"single\"}.\n\
 @seealso{e, pi, log, exp}\n\
 @end deftypefn")
 {
 \n\
 Note that NA always compares not equal to NA (NA != NA).\n\
 To find NA values, use the @code{isna} function.\n\
 \n\
 When called with no arguments, return a scalar with the value @samp{NA}.\n\
+\n\
 When called with a single argument, return a square matrix with the dimension\n\
-specified.  When called with more than one scalar argument the first two\n\
+specified.\n\
-arguments are taken as the number of rows and columns and any further\n\
+\n\
-arguments specify additional matrix dimensions.\n\
+When called with more than one scalar argument the first two arguments are\n\
+taken as the number of rows and columns and any further arguments specify\n\
+additional matrix dimensions.\n\
+\n\
 The optional argument @var{class} specifies the return type and may be\n\
 either @qcode{\"double\"} or @qcode{\"single\"}.\n\
 @seealso{isna}\n\
 @end deftypefn")
 {
 "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {} false (@var{x})\n\
 @deftypefnx {Built-in Function} {} false (@var{n}, @var{m})\n\
 @deftypefnx {Built-in Function} {} false (@var{n}, @var{m}, @var{k}, @dots{})\n\
 Return a matrix or N-dimensional array whose elements are all logical 0.\n\
+\n\
 If invoked with a single scalar integer argument, return a square\n\
-matrix of the specified size.  If invoked with two or more scalar\n\
+matrix of the specified size.\n\
-integer arguments, or a vector of integer values, return an array with\n\
+\n\
-given dimensions.\n\
+If invoked with two or more scalar integer arguments, or a vector of integer\n\
+values, return an array with given dimensions.\n\
 @seealso{true}\n\
 @end deftypefn")
 {
 return fill_matrix (args, false, "false");
 }
 "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {} true (@var{x})\n\
 @deftypefnx {Built-in Function} {} true (@var{n}, @var{m})\n\
 @deftypefnx {Built-in Function} {} true (@var{n}, @var{m}, @var{k}, @dots{})\n\
 Return a matrix or N-dimensional array whose elements are all logical 1.\n\
+\n\
 If invoked with a single scalar integer argument, return a square\n\
-matrix of the specified size.  If invoked with two or more scalar\n\
+matrix of the specified size.\n\
-integer arguments, or a vector of integer values, return an array with\n\
+\n\
-given dimensions.\n\
+If invoked with two or more scalar integer arguments, or a vector of integer\n\
+values, return an array with given dimensions.\n\
 @seealso{false}\n\
 @end deftypefn")
 {
 return fill_matrix (args, true, "true");
 }
 "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {} eye (@var{n})\n\
 @deftypefnx {Built-in Function} {} eye (@var{m}, @var{n})\n\
 @deftypefnx {Built-in Function} {} eye ([@var{m} @var{n}])\n\
 @deftypefnx {Built-in Function} {} eye (@dots{}, @var{class})\n\
-Return an identity matrix.  If invoked with a single scalar argument @var{n},\n\
+Return an identity matrix.\n\
-return a square @nospell{NxN} identity matrix.  If\n\
+\n\
-supplied two scalar arguments (@var{m}, @var{n}), @code{eye} takes them to be\n\
+If invoked with a single scalar argument @var{n}, return a square\n\
-the number of rows and columns.  If given a vector with two elements,\n\
+@nospell{NxN} identity matrix.\n\
-@code{eye} uses the values of the elements as the number of rows and columns,\n\
+\n\
-respectively.  For example:\n\
+If supplied two scalar arguments (@var{m}, @var{n}), @code{eye} takes them\n\
+to be the number of rows and columns.  If given a vector with two elements,\n\
+@code{eye} uses the values of the elements as the number of rows and\n\
+columns, respectively.  For example:\n\
 \n\
 @example\n\
 @group\n\
 eye (3)\n\
 @result{}  1  0  0\n\
 \n\
 @example\n\
 val = zeros (n,m, \"uint8\")\n\
 @end example\n\
 \n\
-Calling @code{eye} with no arguments is equivalent to calling it\n\
+Calling @code{eye} with no arguments is equivalent to calling it with an\n\
-with an argument of 1.  Any negative dimensions are treated as zero. \n\
+argument of 1.  Any negative dimensions are treated as zero.  These odd\n\
-These odd definitions are for compatibility with @sc{matlab}.\n\
+definitions are for compatibility with @sc{matlab}.\n\
 @seealso{speye, ones, zeros}\n\
 @end deftypefn")
 {
 octave_value retval;
 DEFUN (linspace, args, ,
 "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {} linspace (@var{base}, @var{limit})\n\
 @deftypefnx {Built-in Function} {} linspace (@var{base}, @var{limit}, @var{n})\n\
 Return a row vector with @var{n} linearly spaced elements between\n\
-@var{base} and @var{limit}.  If the number of elements is greater than one,\n\
+@var{base} and @var{limit}.\n\
-then the endpoints @var{base} and @var{limit} are always included in\n\
+\n\
-the range.  If @var{base} is greater than @var{limit}, the elements are\n\
+If the number of elements is greater than one, then the endpoints @var{base}\n\
-stored in decreasing order.  If the number of points is not specified, a\n\
+and @var{limit} are always included in the range.  If @var{base} is greater\n\
-value of 100 is used.\n\
+than @var{limit}, the elements are stored in decreasing order.  If the\n\
-\n\
+number of points is not specified, a value of 100 is used.\n\
-The @code{linspace} function always returns a row vector if both\n\
+\n\
-@var{base} and @var{limit} are scalars.  If one, or both, of them are column\n\
+The @code{linspace} function always returns a row vector if both @var{base}\n\
-vectors, @code{linspace} returns a matrix.\n\
+and @var{limit} are scalars.  If one, or both, of them are column vectors,\n\
+@code{linspace} returns a matrix.\n\
 \n\
 For compatibility with @sc{matlab}, return the second argument (@var{limit})\n\
 if fewer than two values are requested.\n\
 @seealso{logspace}\n\
 @end deftypefn")
 @deftypefn  {Built-in Function} {} reshape (@var{A}, @var{m}, @var{n}, @dots{})\n\
 @deftypefnx {Built-in Function} {} reshape (@var{A}, [@var{m} @var{n} @dots{}])\n\
 @deftypefnx {Built-in Function} {} reshape (@var{A}, @dots{}, [], @dots{})\n\
 @deftypefnx {Built-in Function} {} reshape (@var{A}, @var{size})\n\
 Return a matrix with the specified dimensions (@var{m}, @var{n}, @dots{})\n\
-whose elements are taken from the matrix @var{A}.  The elements of the\n\
+whose elements are taken from the matrix @var{A}.\n\
-matrix are accessed in column-major order (like Fortran arrays are stored).\n\
+\n\
+The elements of the matrix are accessed in column-major order (like Fortran\n\
+arrays are stored).\n\
 \n\
 The following code demonstrates reshaping a 1x4 row vector into a 2x2 square\n\
 matrix.\n\
 \n\
 @example\n\
 2  4\n\
 @end group\n\
 @end example\n\
 \n\
 @noindent\n\
-Note that the total number of elements in the original\n\
+Note that the total number of elements in the original matrix\n\
-matrix (@code{prod (size (@var{A}))}) must match the total number of elements\n\
+(@code{prod (size (@var{A}))}) must match the total number of elements\n\
 in the new matrix (@code{prod ([@var{m} @var{n} @dots{}])}).\n\
 \n\
 A single dimension of the return matrix may be left unspecified and Octave\n\
 will determine its size automatically.  An empty matrix ([]) is used to flag\n\
 the unspecified dimension.\n\
 DEFUN (vec, args, ,
 "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {@var{v} =} vec (@var{x})\n\
 @deftypefnx {Built-in Function} {@var{v} =} vec (@var{x}, @var{dim})\n\
 Return the vector obtained by stacking the columns of the matrix @var{x}\n\
-one above the other.  Without @var{dim} this is equivalent to\n\
+one above the other.\n\
-@code{@var{x}(:)}.  If @var{dim} is supplied, the dimensions of @var{v}\n\
+\n\
-are set to @var{dim} with all elements along the last dimension.\n\
+Without @var{dim} this is equivalent to @code{@var{x}(:)}.\n\
-This is equivalent to @code{shiftdim (@var{x}(:), 1-@var{dim})}.\n\
+\n\
+If @var{dim} is supplied, the dimensions of @var{v} are set to @var{dim}\n\
+with all elements along the last dimension.  This is equivalent to\n\
+@code{shiftdim (@var{x}(:), 1-@var{dim})}.\n\
 @seealso{vech, resize, cat}\n\
 @end deftypefn")
 {
 octave_value retval;
 int dim = 1;
 DEFUN (squeeze, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} squeeze (@var{x})\n\
 Remove singleton dimensions from @var{x} and return the result.\n\
+\n\
 Note that for compatibility with @sc{matlab}, all objects have\n\
 a minimum of two dimensions and row vectors are left unchanged.\n\
 @seealso{reshape}\n\
 @end deftypefn")
 {
 }
 DEFUN (full, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {@var{FM} =} full (@var{SM})\n\
-Return a full storage matrix from a sparse, diagonal, permutation matrix,\n\
+Return a full storage matrix from a sparse, diagonal, or permutation matrix,\n\
 or a range.\n\
 @seealso{sparse, issparse}\n\
 @end deftypefn")
 {
 octave_value retval;
 DEFUN (norm, args, ,
 "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {} norm (@var{A})\n\
 @deftypefnx {Built-in Function} {} norm (@var{A}, @var{p})\n\
 @deftypefnx {Built-in Function} {} norm (@var{A}, @var{p}, @var{opt})\n\
-Compute the p-norm of the matrix @var{A}.  If the second argument is\n\
+Compute the p-norm of the matrix @var{A}.\n\
-missing, @code{p = 2} is assumed.\n\
+\n\
+If the second argument is missing, @code{p = 2} is assumed.\n\
 \n\
 If @var{A} is a matrix (or sparse matrix):\n\
 \n\
 @table @asis\n\
 @item @var{p} = @code{1}\n\
 DEFUN (transpose, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} transpose (@var{x})\n\
 Return the transpose of @var{x}.\n\
+\n\
 This function and @tcode{x.'} are equivalent.\n\
 @seealso{ctranspose}\n\
 @end deftypefn")
 {
 return unary_op_defun_body (octave_value::op_transpose, args);
 DEFUN (ctranspose, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} ctranspose (@var{x})\n\
 Return the complex conjugate transpose of @var{x}.\n\
+\n\
 This function and @tcode{x'} are equivalent.\n\
 @seealso{transpose}\n\
 @end deftypefn")
 {
 return unary_op_defun_body (octave_value::op_hermitian, args);
 DEFUN (plus, args, ,
 "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {} plus (@var{x}, @var{y})\n\
 @deftypefnx {Built-in Function} {} plus (@var{x1}, @var{x2}, @dots{})\n\
 This function and @w{@tcode{x + y}} are equivalent.\n\
+\n\
 If more arguments are given, the summation is applied\n\
 cumulatively from left to right:\n\
 \n\
 @example\n\
 (@dots{}((x1 + x2) + x3) + @dots{})\n\
 DEFUN (mtimes, args, ,
 "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {} mtimes (@var{x}, @var{y})\n\
 @deftypefnx {Built-in Function} {} mtimes (@var{x1}, @var{x2}, @dots{})\n\
 Return the matrix multiplication product of inputs.\n\
+\n\
 This function and @w{@tcode{x * y}} are equivalent.\n\
 If more arguments are given, the multiplication is applied\n\
 cumulatively from left to right:\n\
 \n\
 @example\n\
 DEFUN (mrdivide, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} mrdivide (@var{x}, @var{y})\n\
 Return the matrix right division of @var{x} and @var{y}.\n\
+\n\
 This function and @w{@tcode{x / y}} are equivalent.\n\
 @seealso{mldivide, rdivide, plus, minus}\n\
 @end deftypefn")
 {
 return binary_op_defun_body (octave_value::op_div, args);
 DEFUN (mpower, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} mpower (@var{x}, @var{y})\n\
 Return the matrix power operation of @var{x} raised to the @var{y} power.\n\
+\n\
 This function and @w{@tcode{x ^ y}} are equivalent.\n\
 @seealso{power, mtimes, plus, minus}\n\
 @end deftypefn")
 {
 return binary_op_defun_body (octave_value::op_pow, args);
 DEFUN (mldivide, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} mldivide (@var{x}, @var{y})\n\
 Return the matrix left division of @var{x} and @var{y}.\n\
+\n\
 This function and @w{@tcode{x @xbackslashchar{} y}} are equivalent.\n\
 @seealso{mrdivide, ldivide, rdivide}\n\
 @end deftypefn")
 {
 return binary_op_defun_body (octave_value::op_ldiv, args);
 DEFUN (eq, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} eq (@var{x}, @var{y})\n\
 Return true if the two inputs are equal.\n\
+\n\
 This function is equivalent to @w{@code{x == y}}.\n\
 @seealso{ne, isequal, le, ge, gt, ne, lt}\n\
 @end deftypefn")
 {
 return binary_op_defun_body (octave_value::op_eq, args);
 DEFUN (ne, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} ne (@var{x}, @var{y})\n\
 Return true if the two inputs are not equal.\n\
+\n\
 This function is equivalent to @w{@code{x != y}}.\n\
 @seealso{eq, isequal, le, ge, lt}\n\
 @end deftypefn")
 {
 return binary_op_defun_body (octave_value::op_ne, args);
 DEFUN (times, args, ,
 "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {} times (@var{x}, @var{y})\n\
 @deftypefnx {Built-in Function} {} times (@var{x1}, @var{x2}, @dots{})\n\
 Return the element-by-element multiplication product of inputs.\n\
+\n\
 This function and @w{@tcode{x .* y}} are equivalent.\n\
 If more arguments are given, the multiplication is applied\n\
 cumulatively from left to right:\n\
 \n\
 @example\n\
 DEFUN (rdivide, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} rdivide (@var{x}, @var{y})\n\
 Return the element-by-element right division of @var{x} and @var{y}.\n\
+\n\
 This function and @w{@tcode{x ./ y}} are equivalent.\n\
 @seealso{ldivide, mrdivide, times, plus}\n\
 @end deftypefn")
 {
 return binary_op_defun_body (octave_value::op_el_div, args);
 DEFUN (power, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} power (@var{x}, @var{y})\n\
 Return the element-by-element operation of @var{x} raised to the\n\
-@var{y} power.  If several complex results are possible,\n\
+@var{y} power.\n\
-returns the one with smallest non-negative argument (angle).  Use\n\
-@code{realpow}, @code{realsqrt}, @code{cbrt}, or @code{nthroot} if a\n\
-real result is preferred.\n\
 \n\
 This function and @w{@tcode{x .^ y}} are equivalent.\n\
+\n\
+If several complex results are possible, returns the one with smallest\n\
+non-negative argument (angle).  Use @code{realpow}, @code{realsqrt},\n\
+@code{cbrt}, or @code{nthroot} if a real result is preferred.\n\
+\n\
 @seealso{mpower, realpow, realsqrt, cbrt, nthroot}\n\
 @end deftypefn")
 {
 return binary_op_defun_body (octave_value::op_el_pow, args);
 }
 DEFUN (ldivide, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} ldivide (@var{x}, @var{y})\n\
 Return the element-by-element left division of @var{x} and @var{y}.\n\
+\n\
 This function and @w{@tcode{x .@xbackslashchar{} y}} are equivalent.\n\
 @seealso{rdivide, mldivide, times, plus}\n\
 @end deftypefn")
 {
 return binary_op_defun_body (octave_value::op_el_ldiv, args);
 @deftypefn  {Built-in Function} {} tic ()\n\
 @deftypefnx {Built-in Function} {@var{id} =} tic ()\n\
 @deftypefnx {Built-in Function} {} toc ()\n\
 @deftypefnx {Built-in Function} {} toc (@var{id})\n\
 @deftypefnx {Built-in Function} {@var{val} =} toc (@dots{})\n\
-Set or check a wall-clock timer.  Calling @code{tic} without an\n\
+Set or check a wall-clock timer.\n\
-output argument sets the internal timer state.  Subsequent calls\n\
+\n\
-to @code{toc} return the number of seconds since the timer was set.\n\
+Calling @code{tic} without an output argument sets the internal timer state.\n\
+Subsequent calls to @code{toc} return the number of seconds since the timer\n\
+was set.\n\
 For example,\n\
 \n\
 @example\n\
 @group\n\
 tic ();\n\
 */
 DEFUN (cputime, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {[@var{total}, @var{user}, @var{system}] =} cputime ();\n\
-Return the CPU time used by your Octave session.  The first output is\n\
+Return the CPU time used by your Octave session.\n\
-the total time spent executing your process and is equal to the sum of\n\
+\n\
-second and third outputs, which are the number of CPU seconds spent\n\
+The first output is the total time spent executing your process and is equal\n\
-executing in user mode and the number of CPU seconds spent executing in\n\
+to the sum of second and third outputs, which are the number of CPU seconds\n\
-system mode, respectively.  If your system does not have a way to report\n\
+spent executing in user mode and the number of CPU seconds spent executing\n\
-CPU time usage, @code{cputime} returns 0 for each of its output values.\n\
+in system mode, respectively.\n\
+\n\
+If your system does not have a way to report CPU time usage, @code{cputime}\n\
+returns 0 for each of its output values.\n\
+\n\
 Note that because Octave used some CPU time to start, it is reasonable\n\
 to check to see if @code{cputime} works by checking to see if the total\n\
 CPU time used is nonzero.\n\
 @seealso{tic, toc}\n\
 @end deftypefn")
 "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {[@var{s}, @var{i}] =} sort (@var{x})\n\
 @deftypefnx {Built-in Function} {[@var{s}, @var{i}] =} sort (@var{x}, @var{dim})\n\
 @deftypefnx {Built-in Function} {[@var{s}, @var{i}] =} sort (@var{x}, @var{mode})\n\
 @deftypefnx {Built-in Function} {[@var{s}, @var{i}] =} sort (@var{x}, @var{dim}, @var{mode})\n\
-Return a copy of @var{x} with the elements arranged in increasing\n\
+Return a copy of @var{x} with the elements arranged in increasing order.\n\
-order.  For matrices, @code{sort} orders the elements within columns\n\
+\n\
+For matrices, @code{sort} orders the elements within columns\n\
 \n\
 For example:\n\
 \n\
 @example\n\
 @group\n\
 @deftypefn  {Built-in Function} {} issorted (@var{a})\n\
 @deftypefnx {Built-in Function} {} issorted (@var{a}, @var{mode})\n\
 @deftypefnx {Built-in Function} {} issorted (@var{a}, \"rows\", @var{mode})\n\
 Return true if the array is sorted according to @var{mode}, which\n\
 may be either @qcode{\"ascending\"}, @qcode{\"descending\"}, or\n\
-@qcode{\"either\"}.  By default,  @var{mode} is @qcode{\"ascending\"}.  NaNs\n\
+@qcode{\"either\"}.\n\
-are treated in the same manner as @code{sort}.\n\
+\n\
+By default,  @var{mode} is @qcode{\"ascending\"}.  NaNs are treated in the\n\
+same manner as @code{sort}.\n\
 \n\
 If the optional argument @qcode{\"rows\"} is supplied, check whether\n\
 the array is sorted by rows as output by the function @code{sortrows}\n\
 (with no options).\n\
 \n\
 DEFUN (nth_element, args, ,
 "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {} nth_element (@var{x}, @var{n})\n\
 @deftypefnx {Built-in Function} {} nth_element (@var{x}, @var{n}, @var{dim})\n\
 Select the n-th smallest element of a vector, using the ordering defined by\n\
-@code{sort}.  In other words, the result is equivalent to\n\
+@code{sort}.\n\
-@code{sort(@var{x})(@var{n})}.\n\
+\n\
+The result is equivalent to @code{sort(@var{x})(@var{n})}.\n\
+\n\
 @var{n} can also be a contiguous range, either ascending @code{l:u}\n\
 or descending @code{u:-1:l}, in which case a range of elements is returned.\n\
+\n\
 If @var{x} is an array, @code{nth_element} operates along the dimension\n\
 defined by @var{dim}, or the first non-singleton dimension if @var{dim} is\n\
 not given.\n\
 \n\
-nth_element encapsulates the C++ standard library algorithms nth_element and\n\
+Programming Note: nth_element encapsulates the C++ standard library\n\
-partial_sort.  On average, the complexity of the operation is O(M*log(K)),\n\
+algorithms nth_element and partial_sort.  On average, the complexity of the\n\
-where @w{@code{M = size (@var{x}, @var{dim})}} and\n\
+operation is O(M*log(K)), where @w{@code{M = size (@var{x}, @var{dim})}} and\n\
-@w{@code{K = length (@var{n})}}.\n\
+@w{@code{K = length (@var{n})}}.  This function is intended for cases where\n\
-This function is intended for cases where the ratio K/M is small; otherwise,\n\
+the ratio K/M is small; otherwise, it may be better to use @code{sort}.\n\
-it may be better to use @code{sort}.\n\
 @seealso{sort, min, max}\n\
 @end deftypefn")
 {
 octave_value retval;
 int nargin = args.length ();
 DEFUN (merge, args, ,
 "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {} merge (@var{mask}, @var{tval}, @var{fval})\n\
 @deftypefnx {Built-in Function} {} ifelse (@var{mask}, @var{tval}, @var{fval})\n\
 Merge elements of @var{true_val} and @var{false_val}, depending on the\n\
-value of @var{mask}.  If @var{mask} is a logical scalar, the other two\n\
+value of @var{mask}.\n\
-arguments can be arbitrary values.  Otherwise, @var{mask} must be a logical\n\
+\n\
-array, and @var{tval}, @var{fval} should be arrays of matching class, or\n\
+If @var{mask} is a logical scalar, the other two arguments can be arbitrary\n\
-cell arrays.  In the scalar mask case, @var{tval} is returned if @var{mask}\n\
+values.  Otherwise, @var{mask} must be a logical array, and @var{tval},\n\
-is true, otherwise @var{fval} is returned.\n\
+@var{fval} should be arrays of matching class, or cell arrays.  In the\n\
+scalar mask case, @var{tval} is returned if @var{mask} is true, otherwise\n\
+@var{fval} is returned.\n\
 \n\
 In the array mask case, both @var{tval} and @var{fval} must be either\n\
 scalars or arrays with dimensions equal to @var{mask}.  The result is\n\
 constructed as follows:\n\
 \n\
 result(mask) = tval(mask);\n\
 result(! mask) = fval(! mask);\n\
 @end group\n\
 @end example\n\
 \n\
-@var{mask} can also be arbitrary numeric type, in which case\n\
+@var{mask} can also be arbitrary numeric type, in which case it is first\n\
-it is first converted to logical.\n\
+converted to logical.\n\
 @seealso{logical, diff}\n\
 @end deftypefn")
 {
 int nargin = args.length ();
 octave_value retval;
 }
 DEFUN (repelems, args, ,
 "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} repelems (@var{x}, @var{r})\n\
-Construct a vector of repeated elements from @var{x}.  @var{r}\n\
+Construct a vector of repeated elements from @var{x}.\n\
-is a 2x@var{N} integer matrix specifying which elements to repeat and\n\
+\n\
-how often to repeat each element.\n\
+@var{r} is a 2x@var{N} integer matrix specifying which elements to repeat and\n\
-\n\
+how often to repeat each element.  Entries in the first row, @var{r}(1,j),\n\
-Entries in the first row, @var{r}(1,j), select an element to repeat.\n\
+select an element to repeat.  The corresponding entry in the second row,\n\
-The corresponding entry in the second row, @var{r}(2,j), specifies\n\
+@var{r}(2,j), specifies the repeat count.  If @var{x} is a matrix then the\n\
-the repeat count.  If @var{x} is a matrix then the columns of @var{x} are\n\
+columns of @var{x} are imagined to be stacked on top of each other for\n\
-imagined to be stacked on top of each other for purposes of the selection\n\
+purposes of the selection index.  A row vector is always returned.\n\
-index.  A row vector is always returned.\n\
 \n\
 Conceptually the result is calculated as follows:\n\
 \n\
 @example\n\
 @group\n\
 DEFUN (base64_decode, args, ,
 "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {@var{x} =} base64_decode (@var{s})\n\
 @deftypefnx {Built-in Function} {@var{x} =} base64_decode (@var{s}, @var{dims})\n\
 Decode the double matrix or array @var{x} from the base64 encoded string\n\
-@var{s}.  The optional input parameter @var{dims} should be a vector\n\
+@var{s}.\n\
-containing the dimensions of the decoded array.\n\
+\n\
+The optional input parameter @var{dims} should be a vector containing the\n\
+dimensions of the decoded array.\n\
 @seealso{base64_encode}\n\
 @end deftypefn")
 {
 octave_value retval;

Mercurial > octave-nkf

comparison libinterp/corefcn/data.cc @ 20207:4f45eaf83908 stable