changeset 25106:d7ad543255c5 stable

doc: Shorten very long first sentences of docstrings (bug #53388). * bsxfun.cc (Fbsxfun), daspk.cc (Fdaspk), dasrt.cc (Fdasrt), dassl.cc (Fdassl), gsvd.cc (Fgsvd), load-save.cc (Foctave_core_file_limit), qz.cc (Fqz), svd.cc (Fsvd), sylvester.cc (Fsylvester), utils.cc (Ferrno), bincoeff.m, bessel.m, krylov.m, expint.m, moment.m: Shorten very long first sentences.
author Rik <rik@octave.org>
date Tue, 03 Apr 2018 21:37:29 -0700
parents dd480b75e6e8
children 13cd142c3f88
files libinterp/corefcn/bsxfun.cc libinterp/corefcn/daspk.cc libinterp/corefcn/dasrt.cc libinterp/corefcn/dassl.cc libinterp/corefcn/gsvd.cc libinterp/corefcn/load-save.cc libinterp/corefcn/qz.cc libinterp/corefcn/svd.cc libinterp/corefcn/sylvester.cc libinterp/corefcn/utils.cc scripts/general/bincoeff.m scripts/help/bessel.m scripts/linear-algebra/krylov.m scripts/specfun/expint.m scripts/statistics/moment.m
diffstat 15 files changed, 72 insertions(+), 35 deletions(-) [+]
line wrap: on
line diff
--- a/libinterp/corefcn/bsxfun.cc	Tue Apr 03 12:15:41 2018 +0200
+++ b/libinterp/corefcn/bsxfun.cc	Tue Apr 03 21:37:29 2018 -0700
@@ -321,19 +321,18 @@
 DEFMETHOD (bsxfun, interp,args, ,
            doc: /* -*- texinfo -*-
 @deftypefn {} {} bsxfun (@var{f}, @var{A}, @var{B})
-The binary singleton expansion function performs broadcasting,
-that is, it applies a binary function @var{f} element-by-element to two
-array arguments @var{A} and @var{B}, and expands as necessary
-singleton dimensions in either input argument.
+Apply a binary function @var{f} element-by-element to two array arguments
+@var{A} and @var{B}, expanding singleton dimensions in either input argument as
+necessary.
 
 @var{f} is a function handle, inline function, or string containing the name
-of the function to evaluate.  The function @var{f} must be capable of
-accepting two column-vector arguments of equal length, or one column vector
-argument and a scalar.
+of the function to evaluate.  The function @var{f} must be capable of accepting
+two column-vector arguments of equal length, or one column vector argument and
+a scalar.
 
 The dimensions of @var{A} and @var{B} must be equal or singleton.  The
-singleton dimensions of the arrays will be expanded to the same
-dimensionality as the other array.
+singleton dimensions of the arrays will be expanded to the same dimensionality
+as the other array.
 @seealso{arrayfun, cellfun}
 @end deftypefn */)
 {
--- a/libinterp/corefcn/daspk.cc	Tue Apr 03 12:15:41 2018 +0200
+++ b/libinterp/corefcn/daspk.cc	Tue Apr 03 21:37:29 2018 -0700
@@ -157,7 +157,9 @@
 DEFMETHOD (daspk, interp, args, nargout,
            doc: /* -*- texinfo -*-
 @deftypefn {} {[@var{x}, @var{xdot}, @var{istate}, @var{msg}] =} daspk (@var{fcn}, @var{x_0}, @var{xdot_0}, @var{t}, @var{t_crit})
-Solve the set of differential-algebraic equations
+Solve a set of differential-algebraic equations.
+
+@code{daspk} solves the set of equations
 @tex
 $$ 0 = f (x, \dot{x}, t) $$
 with
--- a/libinterp/corefcn/dasrt.cc	Tue Apr 03 12:15:41 2018 +0200
+++ b/libinterp/corefcn/dasrt.cc	Tue Apr 03 21:37:29 2018 -0700
@@ -196,7 +196,9 @@
 @deftypefnx {} {@dots{} =} dasrt (@var{fcn}, @var{g}, @var{x_0}, @var{xdot_0}, @var{t}, @var{t_crit})
 @deftypefnx {} {@dots{} =} dasrt (@var{fcn}, @var{x_0}, @var{xdot_0}, @var{t})
 @deftypefnx {} {@dots{} =} dasrt (@var{fcn}, @var{x_0}, @var{xdot_0}, @var{t}, @var{t_crit})
-Solve the set of differential-algebraic equations
+Solve a set of differential-algebraic equations.
+
+@code{dasrt} solves the set of equations
 @tex
 $$ 0 = f (x, \dot{x}, t) $$
 with
--- a/libinterp/corefcn/dassl.cc	Tue Apr 03 12:15:41 2018 +0200
+++ b/libinterp/corefcn/dassl.cc	Tue Apr 03 21:37:29 2018 -0700
@@ -157,7 +157,9 @@
 DEFMETHOD (dassl, interp, args, nargout,
            doc: /* -*- texinfo -*-
 @deftypefn {} {[@var{x}, @var{xdot}, @var{istate}, @var{msg}] =} dassl (@var{fcn}, @var{x_0}, @var{xdot_0}, @var{t}, @var{t_crit})
-Solve the set of differential-algebraic equations
+Solve a set of differential-algebraic equations.
+
+@code{dassl} solves the set of equations
 @tex
 $$ 0 = f (x, \dot{x}, t) $$
 with
--- a/libinterp/corefcn/gsvd.cc	Tue Apr 03 12:15:41 2018 +0200
+++ b/libinterp/corefcn/gsvd.cc	Tue Apr 03 21:37:29 2018 -0700
@@ -99,7 +99,10 @@
 @deftypefn  {} {@var{S} =} gsvd (@var{A}, @var{B})
 @deftypefnx {} {[@var{U}, @var{V}, @var{X}, @var{C}, @var{S}] =} gsvd (@var{A}, @var{B})
 @deftypefnx {} {[@var{U}, @var{V}, @var{X}, @var{C}, @var{S}] =} gsvd (@var{A}, @var{B}, 0)
-Compute the generalized singular value decomposition of (@var{A}, @var{B}):
+Compute the generalized singular value decomposition of (@var{A}, @var{B}).
+
+The generalized singular value decomposition is defined by the following
+relations:
 
 @tex
 $$ A = U C X^\dagger $$
--- a/libinterp/corefcn/load-save.cc	Tue Apr 03 12:15:41 2018 +0200
+++ b/libinterp/corefcn/load-save.cc	Tue Apr 03 21:37:29 2018 -0700
@@ -1789,15 +1789,17 @@
 @deftypefn  {} {@var{val} =} octave_core_file_limit ()
 @deftypefnx {} {@var{old_val} =} octave_core_file_limit (@var{new_val})
 @deftypefnx {} {} octave_core_file_limit (@var{new_val}, "local")
-Query or set the internal variable that specifies the maximum amount
-of memory (in kilobytes) of the top-level workspace that Octave will
-attempt to save when writing data to the crash dump file (the name of
-the file is specified by @var{octave_core_file_name}).
+Query or set the internal variable that specifies the maximum amount of memory
+that Octave will save when writing a crash dump file.
 
-If @var{octave_core_file_options} flags specify a binary format,
-then @var{octave_core_file_limit} will be approximately the maximum
-size of the file.  If a text file format is used, then the file could
-be much larger than the limit.  The default value is -1 (unlimited)
+The limit is measured in kilobytes and is applied to the top-level workspace.
+The name of the crash dump file is is specified by
+@var{octave_core_file_name}).
+
+If @var{octave_core_file_options} flags specify a binary format, then
+@var{octave_core_file_limit} will be approximately the maximum size of the
+file.  If a text file format is used, then the file could be much larger than
+the limit.  The default value is -1 (unlimited).
 
 When called from inside a function with the @qcode{"local"} option, the
 variable is changed locally for the function and any subroutines it calls.
--- a/libinterp/corefcn/qz.cc	Tue Apr 03 12:15:41 2018 +0200
+++ b/libinterp/corefcn/qz.cc	Tue Apr 03 21:37:29 2018 -0700
@@ -134,7 +134,10 @@
 @deftypefnx {} {[@var{AA}, @var{BB}, @var{Q}, @var{Z}, @var{V}, @var{W}, @var{lambda}] =} qz (@var{A}, @var{B})
 @deftypefnx {} {[@var{AA}, @var{BB}, @var{Z}] =} qz (@var{A}, @var{B}, @var{opt})
 @deftypefnx {} {[@var{AA}, @var{BB}, @var{Z}, @var{lambda}] =} qz (@var{A}, @var{B}, @var{opt})
-QZ@tie{}decomposition of the generalized eigenvalue problem
+Compute the QZ@tie{}decomposition of a generalized eigenvalue problem.
+
+The generalized eigenvalue problem is defined as
+
 @tex
 $$A x = \lambda B x$$
 @end tex
--- a/libinterp/corefcn/svd.cc	Tue Apr 03 12:15:41 2018 +0200
+++ b/libinterp/corefcn/svd.cc	Tue Apr 03 21:37:29 2018 -0700
@@ -72,7 +72,10 @@
 @deftypefnx {} {[@var{U}, @var{S}, @var{V}] =} svd (@var{A}, "econ")
 @deftypefnx {} {[@var{U}, @var{S}, @var{V}] =} svd (@var{A}, 0)
 @cindex singular value decomposition
-Compute the singular value decomposition of @var{A}
+Compute the singular value decomposition of @var{A}.
+
+The singular value decomposition is defined by the relation
+
 @tex
 $$
  A = U S V^{\dagger}
--- a/libinterp/corefcn/sylvester.cc	Tue Apr 03 12:15:41 2018 +0200
+++ b/libinterp/corefcn/sylvester.cc	Tue Apr 03 21:37:29 2018 -0700
@@ -34,7 +34,9 @@
 DEFUN (sylvester, args, ,
        doc: /* -*- texinfo -*-
 @deftypefn {} {@var{X} =} sylvester (@var{A}, @var{B}, @var{C})
-Solve the Sylvester equation
+Solve the Sylvester equation.
+
+The Sylvester equation is defined as:
 @tex
 $$
  A X + X B = C
@@ -47,7 +49,7 @@
 @end example
 
 @end ifnottex
-using standard @sc{lapack} subroutines.
+The solution is computed using standard @sc{lapack} subroutines.
 
 For example:
 
--- a/libinterp/corefcn/utils.cc	Tue Apr 03 12:15:41 2018 +0200
+++ b/libinterp/corefcn/utils.cc	Tue Apr 03 21:37:29 2018 -0700
@@ -1047,10 +1047,17 @@
 @deftypefn  {} {@var{err} =} errno ()
 @deftypefnx {} {@var{err} =} errno (@var{val})
 @deftypefnx {} {@var{err} =} errno (@var{name})
-Return the current value of the system-dependent variable errno,
-set its value to @var{val} and return the previous value, or return
-the named error code given @var{name} as a character string, or -1
-if @var{name} is not found.
+Query or set the system-dependent variable errno.
+
+When called with no inputs, return the current value of errno.
+
+When called with a numeric input @var{val}, set the current value of errno
+to the specified value.  The previous value of errno is returned as @var{err}.
+
+When called with a character string @var{name}, return the numeric value of
+errno which corresponds to the specified error code.  If @var{name} is not
+a recognized error code then -1 is returned.
+
 @seealso{errno_list}
 @end deftypefn */)
 {
--- a/scripts/general/bincoeff.m	Tue Apr 03 12:15:41 2018 +0200
+++ b/scripts/general/bincoeff.m	Tue Apr 03 21:37:29 2018 -0700
@@ -18,7 +18,9 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {} {} bincoeff (@var{n}, @var{k})
-## Return the binomial coefficient of @var{n} and @var{k}, defined as
+## Return the binomial coefficient of @var{n} and @var{k}.
+##
+## The binomial coefficient is defined as
 ## @tex
 ## $$
 ##  {n \choose k} = {n (n-1) (n-2) \cdots (n-k+1) \over k!}
--- a/scripts/help/bessel.m	Tue Apr 03 12:15:41 2018 +0200
+++ b/scripts/help/bessel.m	Tue Apr 03 21:37:29 2018 -0700
@@ -22,7 +22,10 @@
 ## @deftypefnx {} {[@var{I}, @var{ierr}] =} besseli (@var{alpha}, @var{x}, @var{opt})
 ## @deftypefnx {} {[@var{K}, @var{ierr}] =} besselk (@var{alpha}, @var{x}, @var{opt})
 ## @deftypefnx {} {[@var{H}, @var{ierr}] =} besselh (@var{alpha}, @var{k}, @var{x}, @var{opt})
-## Compute Bessel or Hankel functions of various kinds:
+## Compute Bessel or Hankel functions of various kinds.
+##
+## All functions begin with the prefix @qcode{"bessel"}.  The list of
+## functions is:
 ##
 ## @table @code
 ## @item besselj
--- a/scripts/linear-algebra/krylov.m	Tue Apr 03 12:15:41 2018 +0200
+++ b/scripts/linear-algebra/krylov.m	Tue Apr 03 21:37:29 2018 -0700
@@ -18,14 +18,17 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {} {[@var{u}, @var{h}, @var{nu}] =} krylov (@var{A}, @var{V}, @var{k}, @var{eps1}, @var{pflg})
-## Construct an orthogonal basis @var{u} of block Krylov subspace
+## Construct an orthogonal basis @var{u} of a block Krylov subspace.
+##
+## The block Krylov subspace has the following form:
 ##
 ## @example
 ## [v a*v a^2*v @dots{} a^(k+1)*v]
 ## @end example
 ##
 ## @noindent
-## using Householder reflections to guard against loss of orthogonality.
+## The construction is made with Householder reflections to guard against loss
+## of orthogonality.
 ##
 ## If @var{V} is a vector, then @var{h} contains the Hessenberg matrix
 ## such that @nospell{@tcode{a*u == u*h+rk*ek'}}, in which
--- a/scripts/specfun/expint.m	Tue Apr 03 12:15:41 2018 +0200
+++ b/scripts/specfun/expint.m	Tue Apr 03 21:37:29 2018 -0700
@@ -18,7 +18,9 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {} {} expint (@var{x})
-## Compute the exponential integral:
+## Compute the exponential integral.
+##
+## The exponential integral is defined as:
 ##
 ## @tex
 ## $$
--- a/scripts/statistics/moment.m	Tue Apr 03 12:15:41 2018 +0200
+++ b/scripts/statistics/moment.m	Tue Apr 03 21:37:29 2018 -0700
@@ -22,7 +22,9 @@
 ## @deftypefnx {} {} moment (@var{x}, @var{p}, @var{dim})
 ## @deftypefnx {} {} moment (@var{x}, @var{p}, @var{type}, @var{dim})
 ## @deftypefnx {} {} moment (@var{x}, @var{p}, @var{dim}, @var{type})
-## Compute the @var{p}-th central moment of the vector @var{x}:
+## Compute the @var{p}-th central moment of the vector @var{x}.
+##
+## The @var{p}-th central moment of @var{x} is defined as:
 ##
 ## @tex
 ## $$