# HG changeset patch
# User Rik <rik@octave.org>
# Date 1679672401 25200
# Node ID 073cc98750c616b1ae0a28ba7d251887d735658a
# Parent  9ddaea221f6607cf9d0989dc701006db987ea541
doc: Improve documentation for linspace and logspace functions.

* data.cc (Flinspace), logspace.m: Improve wording and add Programming Notes
section detailing behavior for certain corner cases.

diff -r 9ddaea221f66 -r 073cc98750c6 libinterp/corefcn/data.cc
--- a/libinterp/corefcn/data.cc	Thu Mar 23 16:21:47 2023 -0400
+++ b/libinterp/corefcn/data.cc	Fri Mar 24 08:40:01 2023 -0700
@@ -5598,10 +5598,10 @@
 Return a row vector with @var{n} linearly spaced elements between @var{start}
 and @var{end}.
 
-If the number of elements is greater than one, then the endpoints @var{start}
-and @var{end} are always included in the range.  If @var{start} is greater than
-@var{end}, the elements are stored in decreasing order.  If the number of
-points is not specified, a value of 100 is used.
+If the number of elements @var{n} is greater than one, then the endpoints
+@var{start} and @var{end} are always included in the range.  If @var{start} is
+greater than @var{end}, the elements are stored in decreasing order.  If the
+number of points @var{n} is not specified, a value of 100 is used.
 
 The @code{linspace} function returns a row vector when both @var{start} and
 @var{end} are scalars.  If one, or both, inputs are vectors, then
@@ -5609,8 +5609,11 @@
 each row is an independent sequence between
 @w{@code{@var{start}(@var{row_n}), @var{end}(@var{row_n})}}.
 
-For compatibility with @sc{matlab}, return the second argument (@var{end}) when
-only a single value (@var{n} = 1) is requested.
+Programming Notes: For compatibility with @sc{matlab}, return the second
+argument (@var{end}) when a single value (@var{n} = 1) is requested.  If
+@var{n} is not an integer then @code{floor (@var{n})} is used to round the
+number of elements.  If @var{n} is zero or negative then an empty 1x0 matrix
+is returned.
 @seealso{colon, logspace}
 @end deftypefn */)
 {
diff -r 9ddaea221f66 -r 073cc98750c6 scripts/general/logspace.m
--- a/scripts/general/logspace.m	Thu Mar 23 16:21:47 2023 -0400
+++ b/scripts/general/logspace.m	Fri Mar 24 08:40:01 2023 -0700
@@ -26,6 +26,7 @@
 ## -*- texinfo -*-
 ## @deftypefn  {} {@var{y} =} logspace (@var{a}, @var{b})
 ## @deftypefnx {} {@var{y} =} logspace (@var{a}, @var{b}, @var{n})
+## @deftypefnx {} {@var{y} =} logspace (@var{a}, pi)
 ## @deftypefnx {} {@var{y} =} logspace (@var{a}, pi, @var{n})
 ## Return a row vector with @var{n} elements logarithmically spaced from
 ## @tex
@@ -35,7 +36,7 @@
 ## 10^@var{a} to 10^@var{b}.
 ## @end ifnottex
 ##
-## If @var{n} is unspecified it defaults to 50.
+## If the number of elements @var{n} is unspecified it defaults to 50.
 ##
 ## If @var{b} is equal to
 ## @tex
@@ -58,17 +59,20 @@
 ## @ifnottex
 ## 10^@var{a} and 10^pi,
 ## @end ifnottex
-## in order to be compatible with the corresponding @sc{matlab} function.
+## which is useful in digital signal processing.
 ##
-## Also for compatibility with @sc{matlab}, return the right-hand side of
-## the range
+## Programming Notes: For compatibility with @sc{matlab}, return the right-hand
+## side of the range
 ## @tex
 ## ($10^{b}$)
 ## @end tex
 ## @ifnottex
 ## (10^@var{b})
 ## @end ifnottex
-## when just a single value is requested.
+## when a single value (@var{n} = 1) is requested.
+## If @var{n} is not an integer then @code{floor (@var{n})} is used to round
+## the number of elements.  If @var{n} is zero or negative then an empty 1x0
+## matrix is returned.
 ## @seealso{linspace}
 ## @end deftypefn