changeset 32488:d7a3ed7f2fdc stable

doc: grammarcheck C++ files before 9.1 release. * libinterp/corefcn/graphics.cc, libinterp/corefcn/input.cc, libinterp/corefcn/pr-output.cc, libinterp/corefcn/qz.cc, libinterp/corefcn/sysdep.cc: grammarcheck C++ files before 9.1 release.
author Rik <rik@octave.org>
date Thu, 23 Nov 2023 19:42:27 -0800
parents 998cba4600e9
children a4506463f341
files libinterp/corefcn/compile.cc libinterp/corefcn/graphics.cc libinterp/corefcn/input.cc libinterp/corefcn/pr-output.cc libinterp/corefcn/qz.cc libinterp/corefcn/sysdep.cc
diffstat 6 files changed, 62 insertions(+), 59 deletions(-) [+]
line wrap: on
line diff
--- a/libinterp/corefcn/compile.cc	Thu Nov 23 18:28:08 2023 -0800
+++ b/libinterp/corefcn/compile.cc	Thu Nov 23 19:42:27 2023 -0800
@@ -47,13 +47,13 @@
 
 DEFUN (__dummy_mark_1__, , ,
        doc: /* -*- texinfo -*-
-@deftypefn  {} {} __dummy_mark_1__ ()
+@deftypefn {} {} __dummy_mark_1__ ()
 
-Dummy function that calls the c-function void dummy_mark_1 (void)
+Dummy function that calls the C-function @code{void dummy_mark_1 (void)}
 that does nothing.
 
-Usefull for e.g. marking start and end for Callgrind analyzis
-or as an entry point for gdb.
+This is useful for marking start and end for Callgrind analysis or as an entry
+point for @code{gdb}.
 
 @end deftypefn */)
 {
@@ -64,13 +64,13 @@
 
 DEFUN (__dummy_mark_2__, , ,
        doc: /* -*- texinfo -*-
-@deftypefn  {} {} __dummy_mark_2__ ()
+@deftypefn {} {} __dummy_mark_2__ ()
 
-Dummy function that calls the c-function void dummy_mark_2 (void)
+Dummy function that calls the C-function @code{void dummy_mark_2 (void)}
 that does nothing.
 
-Usefull for e.g. marking start and end for Callgrind analyzis
-or as an entry point for gdb.
+This is useful for marking start and end for Callgrind analysis or as an entry
+point for @code{gdb}.
 
 @end deftypefn */)
 {
@@ -81,7 +81,7 @@
 
 DEFUN (__vm_clear_cache__, , ,
   doc: /* -*- texinfo -*-
-@deftypefn  {} {@var{val} =} __vm_clear_cache__ ()
+@deftypefn {} {@var{val} =} __vm_clear_cache__ ()
 
 Internal function.
 
@@ -94,16 +94,18 @@
 
 DEFUN (__vm_print_trace__, , ,
   doc: /* -*- texinfo -*-
-@deftypefn  {} {@var{prints_trace} =} __vm_print_trace__ ())
+@deftypefn {} {@var{print_trace} =} __vm_print_trace__ ())
 
 Internal function.
 
-Print a debug trace from the VM. Toggles on or off each call.
+Print a debug trace from the VM@.
+
+Toggles on or off each call.
 
-There has to be a breakpoint set in some file for the trace
-to actually print anything.
+There has to be a breakpoint set in some file for the trace to actually print
+anything.
 
-Returns true if a trace will be printed from now on, false otherwise.
+The return value is true if a trace will be printed and false otherwise.
 
 @end deftypefn */)
 {
@@ -114,11 +116,11 @@
 
 DEFUN (__ref_count__, args, ,
   doc: /* -*- texinfo -*-
-@deftypefn  {} {@var{count} =} __ref_count__ (@var{obj}))
+@deftypefn {} {@var{count} =} __ref_count__ (@var{obj}))
 
 Internal function.
 
-Returns reference count for an object.
+Return the reference count for an object.
 
 @end deftypefn */)
 {
@@ -134,13 +136,12 @@
 
 DEFMETHOD (__vm_is_executing__, interp, , ,
   doc: /* -*- texinfo -*-
-@deftypefn  {} {@var{is_executing} =} __vm_is_executing__ ())
+@deftypefn {} {@var{is_executing} =} __vm_is_executing__ ())
 
 Internal function.
 
-Returns true if the VM is executing the function calling __vm_is_executing__ ().
-
-False otherwise.
+Return true if the VM is executing the function calling
+@code{__vm_is_executing__ ()}, and false otherwise.
 
 @end deftypefn */)
 {
@@ -172,27 +173,28 @@
 
 @table @code
 @item __vm_profile__ on
-Start the profiler, clearing all previously collected data if there is any.
+Start the profiler.  Any previously collected data is cleared.
 
 @item __vm_profile__ off
-Stop profiling.  The collected data can later be retrieved and examined
-with @code{T = profile ("info")}.
+Stop profiling.  The collected data can be retrieved and examined with
+@code{T = profile ("info")}.
 
 @item __vm_profile__ clear
 Clear all collected profiler data.
 
 @item __vm_profile__ resume
-Restart profiling without clearing the old data.  All newly collected
+Restart profiling without clearing existing data.  All newly collected
 statistics are added to the existing ones.
 
 @item __vm_profile__
-Toggles between profiling and printing the result of the profiler.
+Toggle between profiling and printing the result of the profiler.
 Clears the profiler on each print.
 
 @item __vm_profile__ info
-Prints the profiler data.
+Print the profiler data.
 
-Not that output to a variable is not implemented yet.
+Programming Note: The calling form that returns profiler data in a variable
+is not implemented yet.
 
 @end table
 
@@ -273,7 +275,7 @@
 DEFMETHOD (__vm_print_bytecode__, interp, args, ,
   doc: /* -*- texinfo -*-
 @deftypefn  {} {@var{success} =} __vm_print_bytecode__ (@var{fn_name}))
-@deftypefnx  {} {@var{success} =} __vm_print_bytecode__ (@var{fn_handle}))
+@deftypefnx {} {@var{success} =} __vm_print_bytecode__ (@var{fn_handle}))
 
 Internal function.
 
@@ -348,7 +350,7 @@
 DEFMETHOD (__vm_is_compiled__, interp, args, ,
   doc: /* -*- texinfo -*-
 @deftypefn  {} {@var{is_compiled} =} __vm_is_compiled__ (@var{fn_name})
-@deftypefnx  {} {@var{is_compiled} =} __vm_is_compiled__ (@var{fn_handle})
+@deftypefnx {} {@var{is_compiled} =} __vm_is_compiled__ (@var{fn_handle})
 
 Internal function.
 
@@ -412,8 +414,8 @@
 DEFMETHOD (__vm_compile__, interp, args, ,
        doc: /* -*- texinfo -*-
 @deftypefn  {} {@var{success} =} __vm_compile__ (@var{fn_name})
-@deftypefnx  {} {@var{success} =} __vm_compile__ (@var{fn_name}, "clear")
-@deftypefnx  {} {@var{success} =} __vm_compile__ (@var{fn_name}, "print")
+@deftypefnx {} {@var{success} =} __vm_compile__ (@var{fn_name}, "clear")
+@deftypefnx {} {@var{success} =} __vm_compile__ (@var{fn_name}, "print")
 
 Internal function.
 
@@ -567,27 +569,25 @@
 @deftypefn  {} {@var{val} =} __vm_enable__ ()
 @deftypefnx {} {@var{old_val} =} __vm_enable__ (@var{new_val})
 @deftypefnx {} {@var{old_val} =} __vm_enable__ (@var{new_val}, "local")
-Query or set whether Octave automatically compiles functions to bytecode
-and executes them in a virtual machine (VM).
+Query or set the internal variable that determines whether Octave automatically
+compiles functions to bytecode and executes them in a virtual machine (VM).
 
-Note that the virtual machine feature is experimental.
+@strong{Warning:} The virtual machine feature is experimental.
 
-The default value is currently false, while the VM is still experimental.
-Users need to explicitly call @code{__vm_enable__ (1)} to enable it.
+The default value is false while the VM is still experimental.
+Users must explicitly call @code{__vm_enable__ (1)} to use it.
 
-When false, Octave uses a traditional tree walker
-to evaluate statements parsed from m-code.  When true, Octave translates parsed
-statements to an intermediate representation that is then evaluated by a
-virtual machine.
+When false, Octave uses a traditional tree walker to evaluate statements parsed
+from m-code.  When true, Octave translates parsed statements to an intermediate
+representation that is then evaluated by a virtual machine.
 
 When called from inside a function with the @qcode{"local"} option, the setting
 is changed locally for the function and any subroutines it calls.  The original
 setting is restored when exiting the function.
 
-Once compiled to bytecode, the function will always be evaluated by the
-VM no matter the state of @qcode{"__vm_enable__"}, until the bytecode is
-cleared, by e.g. @qcode{"clear all"} or an modification to the
-function's m-file.
+Once compiled to bytecode, the function will always be evaluated by the VM
+regardless of the state of @code{__vm_enable__}, until the bytecode is cleared
+by, e.g., @qcode{"clear all"}, or a modification to the function's m-file.
 
 @seealso{__vm_compile__}
 
--- a/libinterp/corefcn/graphics.cc	Thu Nov 23 18:28:08 2023 -0800
+++ b/libinterp/corefcn/graphics.cc	Thu Nov 23 19:42:27 2023 -0800
@@ -12134,6 +12134,7 @@
 set (h, props);
 @end group
 @end example
+
 @end itemize
 
 The three syntaxes for setting properties may appear in any combination.
--- a/libinterp/corefcn/input.cc	Thu Nov 23 18:28:08 2023 -0800
+++ b/libinterp/corefcn/input.cc	Thu Nov 23 19:42:27 2023 -0800
@@ -1577,7 +1577,7 @@
 @deftypefnx {} {@var{old_encoding} =} mfile_encoding (@var{new_encoding})
 Query or set the encoding that is used for reading m-files.
 
-The input and output are strings naming an encoding, e.g., "utf-8".
+The input and output are strings naming an encoding, e.g., @qcode{"utf-8"}.
 
 This encoding is used by Octave's parser when reading m-files unless a
 different encoding was set for a specific directory containing m-files using
--- a/libinterp/corefcn/pr-output.cc	Thu Nov 23 18:28:08 2023 -0800
+++ b/libinterp/corefcn/pr-output.cc	Thu Nov 23 19:42:27 2023 -0800
@@ -3936,6 +3936,7 @@
 @end group
 @end example
 
+@noindent
 where spaces have been added for clarity to show the sign bit, the 11-bit
 exponent, and the 52-bit mantissa, in that order.  Together they represent
 @code{pi} as an IEEE 754 double precision floating point number in the normal
@@ -3956,6 +3957,7 @@
 @end group
 @end example
 
+@noindent
 shown here with spaces added for clarity.  Compare with the previous bit string
 from @code{format bit} to see the grouping into bytes and their ordering.
 
--- a/libinterp/corefcn/qz.cc	Thu Nov 23 18:28:08 2023 -0800
+++ b/libinterp/corefcn/qz.cc	Thu Nov 23 19:42:27 2023 -0800
@@ -61,7 +61,7 @@
 
 DEFUN (qz, args, nargout,
        doc: /* -*- texinfo -*-
-@deftypefn {} {[@var{AA}, @var{BB}, @var{Q}, @var{Z}, @var{V}, @var{W}] =} qz (@var{A}, @var{B})
+@deftypefn  {} {[@var{AA}, @var{BB}, @var{Q}, @var{Z}, @var{V}, @var{W}] =} qz (@var{A}, @var{B})
 @deftypefnx {} {[@var{AA}, @var{BB}, @var{Q}, @var{Z}, @var{V}, @var{W}] =} qz (@var{A}, @var{B}, @var{opt})
 Compute the QZ@tie{}decomposition of a generalized eigenvalue problem.
 
@@ -81,8 +81,8 @@
 @enumerate
 @item @code{[@var{AA}, @var{BB}, @var{Q}, @var{Z}, @var{V}, @var{W}, @var{lambda}] = qz (@var{A}, @var{B})}
 
-Compute the complex QZ@tie{}decomposition, generalized eigenvectors, and generalized
-eigenvalues.
+Compute the complex QZ@tie{}decomposition, generalized eigenvectors, and
+generalized eigenvalues.
 @tex
 $$ AA = Q^T AZ, BB = Q^T BZ $$
 $$ { \rm diag }(BB)AV = BV{ \rm diag }(AA) $$
@@ -102,20 +102,20 @@
 
 @end ifnottex
 with @var{AA} and @var{BB} upper triangular, and @var{Q} and @var{Z}
-unitary. The matrices @var{V} and @var{W} respectively contain the right
+unitary.  The matrices @var{V} and @var{W} respectively contain the right
 and left generalized eigenvectors.
 
 @item @code{[@var{AA}, @var{BB}, @var{Z} @{, @var{lambda}@}] = qz (@var{A}, @var{B}, @var{opt})}
 
 The @var{opt} argument must be equal to either @qcode{"real"} or
-@qcode{"complex"}. If it is equal to @qcode{"complex"}, then this
+@qcode{"complex"}.  If it is equal to @qcode{"complex"}, then this
 calling form is equivalent to the first one with only two input
 arguments.
 
 If @var{opt} is equal to @qcode{"real"}, then the real QZ decomposition
-is computed. In particular, @var{AA} is only guaranteed to be
+is computed.  In particular, @var{AA} is only guaranteed to be
 quasi-upper triangular with 1-by-1 and 2-by-2 blocks on the diagonal,
-and @var{Q} and @var{Z} are orthogonal. The identities mentioned above
+and @var{Q} and @var{Z} are orthogonal.  The identities mentioned above
 for right and left generalized eigenvectors are only verified if
 @var{AA} is upper triangular (i.e., when all the generalized eigenvalues
 are real, in which case the real and complex QZ coincide).
--- a/libinterp/corefcn/sysdep.cc	Thu Nov 23 18:28:08 2023 -0800
+++ b/libinterp/corefcn/sysdep.cc	Thu Nov 23 19:42:27 2023 -0800
@@ -772,11 +772,9 @@
 
 DEFUN (isenv, args, ,
        doc: /* -*- texinfo -*-
-@deftypefn {} {@var{val} =} isenv (@var{var})
-Check if the environment variable @var{var} exists.
-
-This function returns true if an environment variable with the name @var{var}
-exists.  Otherwise, it returns false.
+@deftypefn {} {@var{tf} =} isenv (@var{var})
+Return true if the variable @var{var} is an environment variable, and false
+otherwise.
 
 For example,
 
@@ -785,7 +783,8 @@
 @end example
 
 @noindent
-returns true if an environment variable with the name @qcode{"PATH"} exists.
+will typically return true on UNIX systems because @qcode{"PATH"} is an
+environment variable for UNIX.
 @seealso{getenv, setenv, unsetenv}
 @end deftypefn */)
 {
@@ -850,7 +849,8 @@
 
 DEFUN (unsetenv, args, ,
        doc: /* -*- texinfo -*-
-@deftypefn {} {@var{status} =} unsetenv (@var{var})
+@deftypefn  {} {} unsetenv ("@var{var}")
+@deftypefnx {} {@var{status} =} unsetenv ("@var{var}")
 Delete the environment variable @var{var}.
 
 Return 0 if the variable was deleted, or did not exist, and -1 if an error