changeset 25113:476fc012d09a stable

doc: Shorten very long first sentences of docstrings (bug #53388). * syscalls.cc (FO_APPEND, FO_ASYNC, FO_CREAT, FO_EXCL, FO_NONBLOCK, FO_RDONLY, FO_RDWR, FO_SYNC, FO_TRUNC, FO_WRONLY, FWNOHANG, FWUNTRACED, FWCONTINUE): Shorten very long first docstring sentences. chol.cc (Fcholdelete, Fcholshift): Likewise. qr.cc (Fqrupdate, Fqrinsert, Fqrdelete, Fqrshift): Likewise. ode15i.m (ode15i): Likewise. ode15s.m (ode15s): Likewise.
author John W. Eaton <jwe@octave.org>
date Wed, 04 Apr 2018 06:54:11 -0400
parents 959d6c3da166
children f191e1a26095
files libinterp/corefcn/syscalls.cc libinterp/dldfcn/chol.cc libinterp/dldfcn/qr.cc scripts/ode/ode15i.m scripts/ode/ode15s.m
diffstat 5 files changed, 82 insertions(+), 42 deletions(-) [+]
line wrap: on
line diff
--- a/libinterp/corefcn/syscalls.cc	Wed Apr 04 06:05:27 2018 -0400
+++ b/libinterp/corefcn/syscalls.cc	Wed Apr 04 06:54:11 2018 -0400
@@ -1414,9 +1414,11 @@
 DEFUNX ("O_APPEND", FO_APPEND, args, ,
         doc: /* -*- texinfo -*-
 @deftypefn {} {} O_APPEND ()
-Return the numerical value of the file status flag that may be
-returned by @code{fcntl} to indicate each write operation appends,
-or that may be passed to @code{fcntl} to set the write mode to append.
+Return the numerical value of the @code{O_APPEND} macro.
+
+@code{O_APPEND} is file status flag that may be returned by @code{fcntl}
+to indicate each write operation appends, or that may be passed to
+@code{fcntl} to set the write mode to append.
 @seealso{fcntl, O_ASYNC, O_CREAT, O_EXCL, O_NONBLOCK, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY}
 @end deftypefn */)
 {
@@ -1431,8 +1433,10 @@
 DEFUNX ("O_ASYNC", FO_ASYNC, args, ,
         doc: /* -*- texinfo -*-
 @deftypefn {} {} O_ASYNC ()
-Return the numerical value of the file status flag that may be
-returned by @code{fcntl} to indicate asynchronous I/O.
+Return the numerical value of the @code{O_ASYNC} macro.
+
+@code{O_ASYNC} is the file status flag that may be returned by
+@code{fcntl} to indicate asynchronous I/O.
 @seealso{fcntl, O_APPEND, O_CREAT, O_EXCL, O_NONBLOCK, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY}
 @end deftypefn */)
 {
@@ -1447,9 +1451,11 @@
 DEFUNX ("O_CREAT", FO_CREAT, args, ,
         doc: /* -*- texinfo -*-
 @deftypefn {} {} O_CREAT ()
-Return the numerical value of the file status flag that may be
-returned by @code{fcntl} to indicate that a file should be created if it
-does not exist.
+Return the numerical value of the @code{O_CREAT}.
+
+@code{O_CREAT} is the file status flag that may be returned by
+@code{fcntl} to indicate that a file should be created if it does not
+exist.
 @seealso{fcntl, O_APPEND, O_ASYNC, O_EXCL, O_NONBLOCK, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY}
 @end deftypefn */)
 {
@@ -1464,8 +1470,10 @@
 DEFUNX ("O_EXCL", FO_EXCL, args, ,
         doc: /* -*- texinfo -*-
 @deftypefn {} {} O_EXCL ()
-Return the numerical value of the file status flag that may be
-returned by @code{fcntl} to indicate that file locking is used.
+Return the numerical value of the @code{O_EXCL}.
+
+@code{O_EXCL} is the file status flag that may be returned by
+@code{fcntl} to indicate that file locking is used.
 @seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_NONBLOCK, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY}
 @end deftypefn */)
 {
@@ -1480,9 +1488,11 @@
 DEFUNX ("O_NONBLOCK", FO_NONBLOCK, args, ,
         doc: /* -*- texinfo -*-
 @deftypefn {} {} O_NONBLOCK ()
-Return the numerical value of the file status flag that may be
-returned by @code{fcntl} to indicate that non-blocking I/O is in use,
-or that may be passsed to @code{fcntl} to set non-blocking I/O.
+Return the numerical value of the @code{O_NONBLOCK}.
+
+@code{O_NONBLOCK} is the file status flag that may be returned by
+@code{fcntl} to indicate that non-blocking I/O is in use, or that may be
+passsed to @code{fcntl} to set non-blocking I/O.
 @seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_EXCL, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY}
 @end deftypefn */)
 {
@@ -1497,8 +1507,10 @@
 DEFUNX ("O_RDONLY", FO_RDONLY, args, ,
         doc: /* -*- texinfo -*-
 @deftypefn {} {} O_RDONLY ()
-Return the numerical value of the file status flag that may be
-returned by @code{fcntl} to indicate that a file is open for reading only.
+Return the numerical value of the @code{O_RDONLY}.
+
+@code{O_RDONLY} is the file status flag that may be returned by
+@code{fcntl} to indicate that a file is open for reading only.
 @seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_EXCL, O_NONBLOCK, O_RDWR, O_SYNC, O_TRUNC, O_WRONLY}
 @end deftypefn */)
 {
@@ -1513,9 +1525,11 @@
 DEFUNX ("O_RDWR", FO_RDWR, args, ,
         doc: /* -*- texinfo -*-
 @deftypefn {} {} O_RDWR ()
-Return the numerical value of the file status flag that may be
-returned by @code{fcntl} to indicate that a file is open for both reading
-and writing.
+Return the numerical value of the @code{O_RDWR}.
+
+@code{O_RDWR} is the file status flag that may be returned by
+@code{fcntl} to indicate that a file is open for both reading and
+writing.
 @seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_EXCL, O_NONBLOCK, O_RDONLY, O_SYNC, O_TRUNC, O_WRONLY}
 @end deftypefn */)
 {
@@ -1530,9 +1544,10 @@
 DEFUNX ("O_SYNC", FO_SYNC, args, ,
         doc: /* -*- texinfo -*-
 @deftypefn {} {} O_SYNC ()
-Return the numerical value of the file status flag that may be
-returned by @code{fcntl} to indicate that a file is open for synchronous
-I/O.
+Return the numerical value of the @code{O_SYNC}.
+
+@code{O_SYNC} is the file status flag that may be returned by
+@code{fcntl} to indicate that a file is open for synchronous I/O
 @seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_EXCL, O_NONBLOCK, O_RDONLY, O_RDWR, O_TRUNC, O_WRONLY}
 @end deftypefn */)
 {
@@ -1547,9 +1562,11 @@
 DEFUNX ("O_TRUNC", FO_TRUNC, args, ,
         doc: /* -*- texinfo -*-
 @deftypefn {} {} O_TRUNC ()
-Return the numerical value of the file status flag that may be
-returned by @code{fcntl} to indicate that if file exists, it should be
-truncated when writing.
+Return the numerical value of the @code{O_TRUNC}.
+
+@code{O_TRUNC} is the file status flag that may be returned by
+@code{fcntl} to indicate that if file exists, it should be truncated
+when writing.
 @seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_EXCL, O_NONBLOCK, O_RDONLY, O_RDWR, O_SYNC, O_WRONLY}
 @end deftypefn */)
 {
@@ -1564,8 +1581,10 @@
 DEFUNX ("O_WRONLY", FO_WRONLY, args, ,
         doc: /* -*- texinfo -*-
 @deftypefn {} {} O_WRONLY ()
-Return the numerical value of the file status flag that may be
-returned by @code{fcntl} to indicate that a file is open for writing only.
+Return the numerical value of the @code{O_WRONLY}.
+
+@code{O_WRONLY} is the file status flag that may be returned by
+@code{fcntl} to indicate that a file is open for writing only
 @seealso{fcntl, O_APPEND, O_ASYNC, O_CREAT, O_EXCL, O_NONBLOCK, O_RDONLY, O_RDWR, O_SYNC, O_TRUNC}
 @end deftypefn */)
 {
@@ -1580,9 +1599,11 @@
 DEFUNX ("WNOHANG", FWNOHANG, args, ,
         doc: /* -*- texinfo -*-
 @deftypefn {} {} WNOHANG ()
-Return the numerical value of the option argument that may be
-passed to @code{waitpid} to indicate that it should return its status
-immediately instead of waiting for a process to exit.
+Return the numerical value of the @code{WNOHANG} macro.
+
+@code{WNOHANG} is the option argument that may be passed to
+@code{waitpid} to indicate that it should return its status immediately
+instead of waiting for a process to exit.
 @seealso{waitpid, WUNTRACED, WCONTINUE}
 @end deftypefn */)
 {
@@ -1592,8 +1613,10 @@
 DEFUNX ("WUNTRACED", FWUNTRACED, args, ,
         doc: /* -*- texinfo -*-
 @deftypefn {} {} WUNTRACED ()
-Return the numerical value of the option argument that may be
-passed to @code{waitpid} to indicate that it should also return if the child
+Return the numerical value of the @code{WUNTRACED} macro.
+
+@code{WUNTRACED} is the option argument that may be passed to
+@code{waitpid} to indicate that it should also return if the child
 process has stopped but is not traced via the @code{ptrace} system call
 @seealso{waitpid, WNOHANG, WCONTINUE}
 @end deftypefn */)
@@ -1604,9 +1627,11 @@
 DEFUNX ("WCONTINUE", FWCONTINUE, args, ,
         doc: /* -*- texinfo -*-
 @deftypefn {} {} WCONTINUE ()
-Return the numerical value of the option argument that may be
-passed to @code{waitpid} to indicate that it should also return if a stopped
-child has been resumed by delivery of a @code{SIGCONT} signal.
+Return the numerical value of the @code{WCONTINUE} macro.
+
+@code{WCONTINUE} is the option argument that may be passed to
+@code{waitpid} to indicate that it should also return if a stopped child
+has been resumed by delivery of a @code{SIGCONT} signal.
 @seealso{waitpid, WNOHANG, WUNTRACED}
 @end deftypefn */)
 {
--- a/libinterp/dldfcn/chol.cc	Wed Apr 04 06:05:27 2018 -0400
+++ b/libinterp/dldfcn/chol.cc	Wed Apr 04 06:54:11 2018 -0400
@@ -796,6 +796,8 @@
            doc: /* -*- texinfo -*-
 @deftypefn  {} {@var{R1} =} cholinsert (@var{R}, @var{j}, @var{u})
 @deftypefnx {} {[@var{R1}, @var{info}] =} cholinsert (@var{R}, @var{j}, @var{u})
+Update a Cholesky factorization given a row or column to insert in the original factored matrix.
+
 Given a Cholesky@tie{}factorization of a real symmetric or complex Hermitian
 positive definite matrix @w{@var{A} = @var{R}'*@var{R}}, @var{R}@tie{}upper
 triangular, return the Cholesky@tie{}factorization of
@@ -1048,6 +1050,8 @@
 DEFUN_DLD (choldelete, args, ,
            doc: /* -*- texinfo -*-
 @deftypefn {} {@var{R1} =} choldelete (@var{R}, @var{j})
+Update a Cholesky factorization given a row or column to delete from the original factored matrix.
+
 Given a Cholesky@tie{}factorization of a real symmetric or complex Hermitian
 positive definite matrix @w{@var{A} = @var{R}'*@var{R}}, @var{R}@tie{}upper
 triangular, return the Cholesky@tie{}factorization of @w{A(p,p)}, where
@@ -1170,6 +1174,8 @@
 DEFUN_DLD (cholshift, args, ,
            doc: /* -*- texinfo -*-
 @deftypefn {} {@var{R1} =} cholshift (@var{R}, @var{i}, @var{j})
+Update a Cholesky factorization given a range of columns to shift in the original factored matrix.
+
 Given a Cholesky@tie{}factorization of a real symmetric or complex Hermitian
 positive definite matrix @w{@var{A} = @var{R}'*@var{R}}, @var{R}@tie{}upper
 triangular, return the Cholesky@tie{}factorization of
--- a/libinterp/dldfcn/qr.cc	Wed Apr 04 06:05:27 2018 -0400
+++ b/libinterp/dldfcn/qr.cc	Wed Apr 04 06:54:11 2018 -0400
@@ -929,6 +929,8 @@
 DEFUN_DLD (qrupdate, args, ,
            doc: /* -*- texinfo -*-
 @deftypefn {} {[@var{Q1}, @var{R1}] =} qrupdate (@var{Q}, @var{R}, @var{u}, @var{v})
+Update a QR factorization given update vectors or matrices.
+
 Given a QR@tie{}factorization of a real or complex matrix
 @w{@var{A} = @var{Q}*@var{R}}, @var{Q}@tie{}unitary and
 @var{R}@tie{}upper trapezoidal, return the QR@tie{}factorization of
@@ -1091,6 +1093,9 @@
 DEFUN_DLD (qrinsert, args, ,
            doc: /* -*- texinfo -*-
 @deftypefn {} {[@var{Q1}, @var{R1}] =} qrinsert (@var{Q}, @var{R}, @var{j}, @var{x}, @var{orient})
+Update a QR factorization given a row or column to insert in the original factored matrix.
+
+
 Given a QR@tie{}factorization of a real or complex matrix
 @w{@var{A} = @var{Q}*@var{R}}, @var{Q}@tie{}unitary and
 @var{R}@tie{}upper trapezoidal, return the QR@tie{}factorization of
@@ -1287,6 +1292,8 @@
 DEFUN_DLD (qrdelete, args, ,
            doc: /* -*- texinfo -*-
 @deftypefn {} {[@var{Q1}, @var{R1}] =} qrdelete (@var{Q}, @var{R}, @var{j}, @var{orient})
+Update a QR factorization given a row or column to delete from the original factored matrix.
+
 Given a QR@tie{}factorization of a real or complex matrix
 @w{@var{A} = @var{Q}*@var{R}}, @var{Q}@tie{}unitary and
 @var{R}@tie{}upper trapezoidal, return the QR@tie{}factorization of
@@ -1532,6 +1539,8 @@
 DEFUN_DLD (qrshift, args, ,
            doc: /* -*- texinfo -*-
 @deftypefn {} {[@var{Q1}, @var{R1}] =} qrshift (@var{Q}, @var{R}, @var{i}, @var{j})
+Update a QR factorization given a range of columns to shift in the original factored matrix.
+
 Given a QR@tie{}factorization of a real or complex matrix
 @w{@var{A} = @var{Q}*@var{R}}, @var{Q}@tie{}unitary and
 @var{R}@tie{}upper trapezoidal, return the QR@tie{}factorization
--- a/scripts/ode/ode15i.m	Wed Apr 04 06:05:27 2018 -0400
+++ b/scripts/ode/ode15i.m	Wed Apr 04 06:54:11 2018 -0400
@@ -22,11 +22,11 @@
 ## @deftypefnx {} {[@var{t}, @var{y}, @var{te}, @var{ye}, @var{ie}] =} ode15i (@dots{})
 ## @deftypefnx {} {@var{solution} =} ode15i (@dots{})
 ## @deftypefnx {} {} ode15i (@dots{})
+## Solve a set of fully-implicit Ordinary Differential Equations (ODEs) or
+## index 1 Differential Algebraic Equations (DAEs).
 ##
-## Solve a set of fully-implicit Ordinary Differential Equations (ODEs) or
-## Differential Algebraic Equations (DAEs) of index 1, with a variable step,
-## variable order BDF (Backward Differentiation Formula) method that ranges
-## from order 1 to 5.
+## @code{ode15i} uses a variable step, variable order BDF (Backward
+## Differentiation Formula) method that ranges from order 1 to 5.
 ##
 ## @var{fun} is a function handle, inline function, or string containing the
 ## name of the function that defines the ODE: @code{0 = f(t,y,yp)}.  The
--- a/scripts/ode/ode15s.m	Wed Apr 04 06:05:27 2018 -0400
+++ b/scripts/ode/ode15s.m	Wed Apr 04 06:54:11 2018 -0400
@@ -22,11 +22,11 @@
 ## @deftypefnx {} {[@var{t}, @var{y}, @var{te}, @var{ye}, @var{ie}] =} ode15s (@dots{})
 ## @deftypefnx {} {@var{solution} =} ode15s (@dots{})
 ## @deftypefnx {} {} ode15s (@dots{})
+## Solve a set of stiff Ordinary Differential Equations (ODEs) or stiff
+## semi-explicit index 1 Differential Algebraic Equations (DAEs).
 ##
-## Solve a set of stiff Ordinary Differential Equations (ODEs) or stiff
-## semi-explicit Differential Algebraic Equations (DAEs) of index 1, with a
-## variable step, variable order BDF (Backward Differentiation Formula) method
-## that ranges from order 1 to 5.
+## @code{ode15s} uses a variable step, variable order BDF (Backward
+## Differentiation Formula) method that ranges from order 1 to 5.
 ##
 ## @var{fun} is a function handle, inline function, or string containing the
 ## name of the function that defines the ODE: @code{y' = f(t,y)}.  The function