Add more comprehensive documentation

Author: ejovo13

doc/specs/stdlib_math.md

@@ -111,16 +111,19 @@ Function.
 
 #### Argument(s)
 
-`start`: Shall be scalar of any numeric type. This argument is `intent(in)`.
+`start`: Shall be scalar of any numeric type or kind. This argument is `intent(in)`.
 `end`: Shall be the same `type` and `kind` as `start`. This argument is `intent(in)`.
 `n`: Shall be an integer specifying the length of the output. This argument is `optional` and `intent(in)`.
 
 #### Output value or Result value
 
-The output is a rank 1 array of `type` and `kind`, whose length is either 100 (default value) or `n`.
+The output is a rank 1 array whose length is either 100 (default value) or `n`.
 
 If `n` == 1, return a rank 1 array whose only element is `end`.
-If `n` <= 0, return a rank 1 array with length 0
+If `n` <= 0, return a rank 1 array with length 0.
+
+If `start`/`end` are real or complex types, the `result` will be the same `type` and `kind` as `start`/`end`.
+If `start`/`end` are integer types, the `result` will default to a double precision real array.
 
 #### Examples
 
@@ -144,17 +147,17 @@ end program demo_linspace_complex
 
 ##### Example 2:
 
-Here inputs are of type `integer` and kind `int16`
+Here inputs are of type `integer` and kind `int16`, with the result defaulting to double precision real.
 ```fortran
 program demo_linspace_int16
   use stdlib_math, only: linspace
-  use stdlib_kinds, only: int16
+  use stdlib_kinds, only: int16, dp
   implicit none
 
   integer(int16) :: start = 10_int16
   integer(int16) :: end = 23_int16
 
-  integer(int16) :: r(15)
+  real(dp) :: r(15)
 
   r = linspace(start, end, 15)
 end program demo_linspace_int16
@@ -164,7 +167,7 @@ end program demo_linspace_int16
 
 #### Description
 
-Returns a logarithmically spaced rank 1 array from [`base`^`start`, `base`^`end`]. The default size of the array is 100. Optionally, you can specify the length of the returned array by passing `n`.
+Returns a logarithmically spaced rank 1 array from [`base`^`start`, `base`^`end`]. The default size of the array is 50. Optionally, you can specify the length of the returned array by passing `n`. You can also specify the `base` used to compute the range (default 10).
 
 #### Syntax
 
@@ -180,52 +183,95 @@ Function.
 
 #### Argument(s)
 
-`start`: Shall be a scalar of any numeric type. This argument is `intent(in)`.
+`start`: Shall be a scalar of any numeric type. All kinds are supported for real and complex arguments. For integers, only the default kind is currently implemented. This argument is `intent(in)`.
 `end`: Shall be the same `type` and `kind` as `start`. This argument is `intent(in)`.
 `n`: Shall be an integer specifying the length of the output. This argument is `optional` and `intent(in)`.
-`base` : Shall be a scalar of any numeric type. This argument is `optional` and `intent(in)`
+`base` : Shall be a scalar of any numeric type. All kinds are supported for real and complex arguments. For integers, only the default kind is currently implemented. This argument is `optional` and `intent(in)`.
 
 #### Output value or Result value
 
-The output is a rank 1 array of `type` and `kind`, whose length is either 50 (default value) or `n`.
+The output is a rank 1 array whose length is either 50 (default value) or `n`.
 
 If `n` == 1, return a rank 1 array whose only element is `base`^`end`.
 If `n` <= 0, return a rank 1 array with length 0
 
+The `type` and `kind` of the output is dependent on the `type` and `kind` of the passed parameters.
+
+For function calls where the `base` is not specified: `logspace(start, end)`/`logspace(start, end, n)`, the `type` and `kind` of
+the output follows the same scheme as above for `linspace`.
+>If `start`/`end` are real or complex types, the `result` will be the same `type` and `kind` as `start`/`end`.
+>If `start`/`end` are integer types, the `result` will default to a double precision real array.
+
+For function calls where the `base` is specified, the `type` and `kind` of the result is in accordance with the following table:
+
+| `start`/`end` | `n` | `base` | `output` |
+| ------------- | --- | ------ | -------- |
+| `real(KIND)` | `Integer` | `real(KIND)` | `real(KIND)` |
+| "          " | "       " | `complex(KIND)` | `complex(KIND)` |
+| "          " | "       " | `Integer` | `real(KIND)` |
+| `complex(KIND)` | "       " | `real(KIND)` | `complex(KIND)` |
+| "             " | "       " | `complex(KIND)` | `complex(KIND)` |
+| "             " | "       " | `Integer` | `complex(KIND)` |
+| `Integer` | "        " | `real(KIND)` | `real(KIND)` |
+| "              " | "        " | `complex(KIND)` | `complex(KIND)` |
+| "              " | "        " | `Integer` | `Integer` |
+
 #### Examples
 
 ##### Example 1:
 
-Here inputs are of type `complex` and kind `dp`
+Here inputs are of type `complex` and kind `dp`. `n` and `base` is not specified and thus default to 50 and 10, respectively.
 ```fortran
 program demo_logspace_complex
   use stdlib_math, only: logspace
   use stdlib_kinds, only: dp
   implicit none
 
-  complex(dp) :: start = complex(10.0_dp, 5.0_dp)
-  complex(dp) :: end = complex(-10.0_dp, 15.0_dp)
+  complex(dp) :: start = (10.0_dp, 5.0_dp)
+  complex(dp) :: end = (-10.0_dp, 15.0_dp)
 
-  complex(dp) :: z(11)
+  complex(dp) :: z(11) ! Complex values raised to complex powers results in complex values
 
   z = logspace(start, end, 11)
 end program demo_logspace_complex
 ```
 
 ##### Example 2:
 
-Here inputs are of type `integer` and kind `int16`
+Here inputs are of type `integer` and default kind. `base` is not specified and thus defaults to 10.
 ```fortran
-program demo_logspace_int16
+program demo_logspace_int
   use stdlib_math, only: logspace
-  use stdlib_kinds, only: int16
+  use stdlib_kinds, only: dp
   implicit none
 
-  integer(int16) :: start = 10_int16
-  integer(int16) :: end = 23_int16
+  integer :: start = 10
+  integer :: end = 23
+  integer :: n = 15
+
+  real(dp) :: r(n) ! Integer values raised to real powers results in real values
+
+  r = logspace(start, end, n)
+end program demo_logspace_int
+```
+
+##### Example 3:
+
+Here `start`/`end` are of type `real` and double precision. `base` is type `complex` and also double precision.
+```fortran
+program demo_logspace_rstart_cbase
+  use stdlib_math, only: logspace
+  use stdlib_kinds, only: dp
+  implicit none
+
+  real(dp) :: start = 0.0_dp
+  real(dp) :: end = 3.0_dp
+  integer :: n = 4
+  complex(dp) :: base = (0.0_dp, 1.0_dp)
+
+  complex(dp) :: z(n) ! complex values raised to real powers result in complex values
 
-  integer(int16) :: r(15)
+  z = logspace(start, end, n, base)
 
-  r = logspace(start, end, 15)
-end program demo_logspace_int16
+end program demo_logspace_rstart_cbase
 ```

src/stdlib_math.fypp

@@ -156,7 +156,8 @@ module stdlib_math
   #:for k1, t1 in REAL_KINDS_TYPES
     ! Generate logarithmically spaced sequence from ${k1}$ base to the powers
     ! of ${k1}$ start and end. [base^start, ... , base^end]
-    ! RName = ${RName}$
+    ! Different combinations of parameter types will lead to different result types.
+    ! Those combinations are indicated in the body of each function.
     #:set RName = rname("logspace", 1, t1, k1, "n_rbase")
     module function ${RName}$(start, end, n, base) result(res)
       ${t1}$, intent(in) :: start
@@ -192,7 +193,8 @@ module stdlib_math
   #:for k1, t1 in CMPLX_KINDS_TYPES
     ! Generate logarithmically spaced sequence from ${k1}$ base to the powers
     ! of ${k1}$ start and end. [base^start, ... , base^end]
-    ! RName = ${RName}$
+    ! Different combinations of parameter types will lead to different result types.
+    ! Those combinations are indicated in the body of each function.
     #:set RName = rname("logspace", 1, t1, k1, "n_rbase")
     module function ${RName}$(start, end, n, base) result(res)
       ${t1}$, intent(in) :: start
@@ -225,9 +227,11 @@ module stdlib_math
   #:endfor
   #! ========================================================
   #! ========================================================
+  #! Provide support for Integer start/endpoints
     ! Generate logarithmically spaced sequence from ${k1}$ base to the powers
     ! of ${k1}$ start and end. [base^start, ... , base^end]
-    ! RName = ${RName}$
+    ! Different combinations of parameter types will lead to different result types.
+    ! Those combinations are indicated in the body of each function.
   #:for k1 in REAL_KINDS
     #:set RName = rname("logspace", 1, "integer(int32)", "int32", "n_r" + str(k1) + "base")
     module function ${RName}$(start, end, n, base) result(res)