From 83fc81f94593dae1533d4c0acb2dd9b21285ae88 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Thu, 30 Jul 2020 00:28:48 -0700
Subject: [PATCH 01/67] Add function interfaces

---
 spec/API_specification/functions.md | 113 ++++++++++++++++++++++++++++
 spec/API_specification/index.rst    |   1 +
 2 files changed, 114 insertions(+)
 create mode 100644 spec/API_specification/functions.md

diff --git a/spec/API_specification/functions.md b/spec/API_specification/functions.md
new file mode 100644
index 000000000..667468507
--- /dev/null
+++ b/spec/API_specification/functions.md
@@ -0,0 +1,113 @@
+# Functions
+
+> Array API function specification.
+
+## Conformance
+
+A conforming implementation of the array API standard must provide and support all the functions, arguments, syntax, and semantics described in this specification.
+
+A conforming implementation of the array API standard may provide additional values, objects, properties, and functions beyond those described in this specification.
+
+* * *
+
+## Normative References
+
+The following referenced documents are indispensable for the application of this specification.
+
+-   __IEEE 754-2019: IEEE Standard for Floating-Point Arithmetic.__ Institute of Electrical and Electronic Engineers, New York (2019).
+
+* * *
+
+## Terms and Definitions
+
+For the purposes of this specification, the following terms and definitions apply.
+
+### array
+
+a (usually fixed-size) multidimensional container of items of the same type and size.
+
+### shape
+
+a tuple of `N` non-negative integers that specify the sizes of each dimension and where `N` corresponds to the number of dimensions.
+
+* * *
+
+## Functions
+
+A conforming implementation of the array API standard must provide and support the following functions.
+
+<!-- NOTE: please keep the functions in alphabetical order -->
+
+### abs(x, *, out=None)
+
+Calculates the absolute value for each element `x_i` of the input array `x` (i.e., the element-wise result has the same magnitude as the respective element in `x` but has positive sign).
+
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is `-0`, the result is `+0`.
+-   If `x_i` is `-infinity`, the result is `+infinity`.
+
+#### Parameters
+
+-   **x**: input array.
+-   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+
+#### Returns
+
+-   **out**: an array containing the absolute value of each element in `x`.
+
+### exp(x, *, out=None)
+
+Calculates an implementation-dependent approximation to the exponential function for each element `x_i` of the input array `x` (`e` raised to the power of `x_i`, where `e` is the base of the natural logarithm).
+
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is `+0`, the result is `1`.
+-   If `x_i` is `-0`, the result is `1`.
+-   If `x_i` is `+infinity`, the result is `+infinity`.
+-   If `x_i` is `-infinity`, the result is `+0`.
+
+#### Parameters
+
+-   **x**: input array.
+-   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+
+#### Returns
+
+-   **out**: an array containing the evaluated exponential function result for each element in `x`.
+
+### log(x, *, out=None)
+
+Calculates an implementation-dependent approximation to the natural logarithm for each element `x_i` of the input array `x`.
+
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is less than `0`, the result is `NaN`.
+-   If `x_i` is `+0` or `-0`, the result is `-infinity`.
+-   If `x_i` is `1`, the result is `+0`.
+-   If `x_i` is `+infinity`, the result is `+infinity`.
+
+#### Parameters
+
+-   **x**: input array.
+-   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+
+#### Returns
+
+-   **out**: an array containing the evaluated exponential function result for each element in `x`.
+
+### sqrt(x, *, out=None)
+
+Calculates an implementation-dependent approximation to the square root for each element `x_i` of the input array `x`.
+
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is less than `0`, the result is `NaN`.
+-   If `x_i` is `+0`, the result is `+0`.
+-   If `x_i` is `-0`, the result is `-0`.
+-   If `x_i` is `+infinity`, the result is `+infinity`.
+
+* * *
+
+## Addendum
+
+-   Optional arguments must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments.
+-   The `out` keyword argument must be a tuple with one entry per output.
+-   If `out` is not provided or is `None` (the default), an uninitialized return array must be created for each output.
+-   Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.
\ No newline at end of file
diff --git a/spec/API_specification/index.rst b/spec/API_specification/index.rst
index 524cc2267..b4bfa0a23 100644
--- a/spec/API_specification/index.rst
+++ b/spec/API_specification/index.rst
@@ -6,5 +6,6 @@ API specification
    :maxdepth: 1
 
    array_object
+   functions
    indexing
    casting

From 22a0f95953cbcbc81eb95f298735a1df53278d4e Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Thu, 30 Jul 2020 01:02:31 -0700
Subject: [PATCH 02/67] Add functions

---
 spec/API_specification/functions.md | 226 ++++++++++++++++++++++++++++
 1 file changed, 226 insertions(+)

diff --git a/spec/API_specification/functions.md b/spec/API_specification/functions.md
index 667468507..5a3d3f369 100644
--- a/spec/API_specification/functions.md
+++ b/spec/API_specification/functions.md
@@ -55,6 +55,158 @@ Calculates the absolute value for each element `x_i` of the input array `x` (i.e
 
 -   **out**: an array containing the absolute value of each element in `x`.
 
+### acos(x, *, out=None)
+
+Calculates an implementation-dependent approximation to the inverse cosine for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians and ranges from `+0` to `+π`.
+
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is greater than `1`, the result is `NaN`.
+-   If `x_i` is less than `-1`, the result is `NaN`.
+-   If `x_i` is exactly `1`, the result is `+0`.
+
+#### Parameters
+
+-   **x**: input array.
+-   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+
+#### Returns
+
+-   **out**: an array containing the absolute value of each element in `x`.
+
+### acosh(x, *, out=None)
+
+Calculates an implementation-dependent approximation to the inverse hyperbolic cosine for each element `x_i` of the input array `x`.
+
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is less than `1`, the result is `NaN`.
+-   If `x_i` is `1`, the result is `+0`.
+-   If `x_i` is `+infinity`, the result is `+infinity`.
+
+#### Parameters
+
+-   **x**: input array.
+-   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+
+#### Returns
+
+-   **out**: an array containing the absolute value of each element in `x`.
+
+### asin(x, *, out=None)
+
+Calculates an implementation-dependent approximation to the inverse sine for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians and ranges from `-π/2` to `+π/2`.
+
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is greater than `1`, the result is `NaN`.
+-   If `x_i` is less than `-1`, the result is `NaN`.
+-   If `x_i` is `+0`, the result is `+0`.
+-   If `x_i` is `-0`, the result is `-0`.
+
+#### Parameters
+
+-   **x**: input array.
+-   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+
+#### Returns
+
+-   **out**: an array containing the absolute value of each element in `x`.
+
+### asinh(x, *, out=None)
+
+Calculates an implementation-dependent approximation to the inverse hyperbolic sine for each element `x_i` in the input array `x`.
+
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is `+0`, the result is `+0`.
+-   If `x_i` is `-0`, the result is `-0`.
+-   If `x_i` is `+infinity`, the result is `+infinity`.
+-   If `x_i` is `-infinity`, the result is `-infinity`.
+
+#### Parameters
+
+-   **x**: input array.
+-   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+
+#### Returns
+
+-   **out**: an array containing the absolute value of each element in `x`.
+
+### atan(x, *, out=None)
+
+Calculates an implementation-dependent approximation to the inverse tangent for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians and ranges from `-π/2` to `+π/2`.
+
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is `+0`, the result is `+0`.
+-   If `x_i` is `-0`, the result is `-0`.
+-   If `x_i` is `+infinity`, the result is an implementation-dependent approximation to `+π/2`.
+-   If `x_i` is `-infinity`, the result is an implementation-dependent approximation to `-π/2`.
+
+#### Parameters
+
+-   **x**: input array.
+-   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+
+#### Returns
+
+-   **out**: an array containing the absolute value of each element in `x`.
+
+### atanh(x, *, out=None)
+
+Calculates an implementation-dependent approximation to the inverse hyperbolic tangent for each element `x_i` of the input array `x`.
+
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is less than `-1`, the result is `NaN`.
+-   If `x_i` is greater than `1`, the result is `NaN`.
+-   If `x_i` is `-1`, the result is `-infinity`.
+-   If `x_i` is `+1`, the result is `+infinity`.
+-   If `x_i` is `+0`, the result is `+0`.
+-   If `x_i` is `-0`, the result is `-0`.
+
+#### Parameters
+
+-   **x**: input array.
+-   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+
+#### Returns
+
+-   **out**: an array containing the absolute value of each element in `x`.
+
+### cos(x, *, out=None)
+
+Calculates an implementation-dependent approximation to the cosine for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.
+
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is `+0`, the result is `1`.
+-   If `x_i` is `-0`, the result is `1`.
+-   If `x_i` is `+infinity`, the result is `NaN`.
+-   If `x_i` is `-infinity`, the result is `NaN`.
+
+#### Parameters
+
+-   **x**: input array.
+-   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+
+#### Returns
+
+-   **out**: an array containing the absolute value of each element in `x`.
+
+### cosh(x, *, out=None)
+
+Calculates an implementation-dependent approximation to the hyperbolic cosine for each element `x_i` in the input array `x`.
+
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is `+0`, the result is `1`.
+-   If `x_i` is `-0`, the result is `1`.
+-   If `x_i` is `+infinity`, the result is `+infinity`.
+-   If `x_i` is `-infinity`, the result is `+infinity`.
+
+#### Parameters
+
+-   **x**: input array.
+-   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+
+#### Returns
+
+-   **out**: an array containing the absolute value of each element in `x`.
+
 ### exp(x, *, out=None)
 
 Calculates an implementation-dependent approximation to the exponential function for each element `x_i` of the input array `x` (`e` raised to the power of `x_i`, where `e` is the base of the natural logarithm).
@@ -93,6 +245,43 @@ Calculates an implementation-dependent approximation to the natural logarithm fo
 
 -   **out**: an array containing the evaluated exponential function result for each element in `x`.
 
+### sin(x, *, out=None)
+
+Calculates an implementation-dependent approximation to the sine for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.
+
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is `+0`, the result is `+0`.
+-   If `x_i` is `-0`, the result is `-0`.
+-   If `x_i` is `+infinity` or `-infinity`, the result is `NaN`.
+
+#### Parameters
+
+-   **x**: input array.
+-   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+
+#### Returns
+
+-   **out**: an array containing the absolute value of each element in `x`.
+
+### sinh(x, *, out=None)
+
+Calculates an implementation-dependent approximation to the hyperbolic sine for each element `x_i` of the input array `x`.
+
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is `+0`, the result is `+0`.
+-   If `x_i` is `-0`, the result is `-0`.
+-   If `x_i` is `+infinity`, the result is `+infinity`.
+-   If `x_i` is `-infinity`, the result is `-infinity`.
+
+#### Parameters
+
+-   **x**: input array.
+-   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+
+#### Returns
+
+-   **out**: an array containing the absolute value of each element in `x`.
+
 ### sqrt(x, *, out=None)
 
 Calculates an implementation-dependent approximation to the square root for each element `x_i` of the input array `x`.
@@ -103,6 +292,43 @@ Calculates an implementation-dependent approximation to the square root for each
 -   If `x_i` is `-0`, the result is `-0`.
 -   If `x_i` is `+infinity`, the result is `+infinity`.
 
+### tan(x, *, out=None)
+
+Calculates an implementation-dependent approximation to the tangent for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.
+
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is `+0`, the result is `+0`.
+-   If `x_i` is `-0`, the result is `-0`.
+-   If `x_i` is `+infinity` or `-infinity`, the result is `NaN`.
+
+#### Parameters
+
+-   **x**: input array.
+-   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+
+#### Returns
+
+-   **out**: an array containing the absolute value of each element in `x`.
+
+### tanh(x, *, out=None)
+
+Calculates an implementation-dependent approximation to the hyperbolic tangent for each element `x_i` of the input array `x`.
+
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is `+0`, the result is `+0`.
+-   If `x_i` is `-0`, the result is `-0`.
+-   If `x_i` is `+infinity`, the result is `+1`.
+-   If `x_i` is `-infinity`, the result is `-1`.
+
+#### Parameters
+
+-   **x**: input array.
+-   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+
+#### Returns
+
+-   **out**: an array containing the absolute value of each element in `x`.
+
 * * *
 
 ## Addendum

From 2753c1c36e0b542a82edc47bcf1d6530f00e70d0 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Thu, 30 Jul 2020 01:06:39 -0700
Subject: [PATCH 03/67] Fix descriptions

---
 spec/API_specification/functions.md | 35 ++++++++++++++++++-----------
 1 file changed, 22 insertions(+), 13 deletions(-)

diff --git a/spec/API_specification/functions.md b/spec/API_specification/functions.md
index 5a3d3f369..88d1f43c9 100644
--- a/spec/API_specification/functions.md
+++ b/spec/API_specification/functions.md
@@ -71,7 +71,7 @@ Calculates an implementation-dependent approximation to the inverse cosine for e
 
 #### Returns
 
--   **out**: an array containing the absolute value of each element in `x`.
+-   **out**: an array containing the inverse cosine of each element in `x`.
 
 ### acosh(x, *, out=None)
 
@@ -89,7 +89,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic c
 
 #### Returns
 
--   **out**: an array containing the absolute value of each element in `x`.
+-   **out**: an array containing the inverse hyperbolic cosine of each element in `x`.
 
 ### asin(x, *, out=None)
 
@@ -108,7 +108,7 @@ Calculates an implementation-dependent approximation to the inverse sine for eac
 
 #### Returns
 
--   **out**: an array containing the absolute value of each element in `x`.
+-   **out**: an array containing the inverse sine of each element in `x`.
 
 ### asinh(x, *, out=None)
 
@@ -127,7 +127,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic s
 
 #### Returns
 
--   **out**: an array containing the absolute value of each element in `x`.
+-   **out**: an array containing the inverse hyperbolic sine of each element in `x`.
 
 ### atan(x, *, out=None)
 
@@ -146,7 +146,7 @@ Calculates an implementation-dependent approximation to the inverse tangent for
 
 #### Returns
 
--   **out**: an array containing the absolute value of each element in `x`.
+-   **out**: an array containing the inverse tangent of each element in `x`.
 
 ### atanh(x, *, out=None)
 
@@ -167,7 +167,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic t
 
 #### Returns
 
--   **out**: an array containing the absolute value of each element in `x`.
+-   **out**: an array containing the inverse hyperbolic tangent of each element in `x`.
 
 ### cos(x, *, out=None)
 
@@ -186,7 +186,7 @@ Calculates an implementation-dependent approximation to the cosine for each elem
 
 #### Returns
 
--   **out**: an array containing the absolute value of each element in `x`.
+-   **out**: an array containing the cosine of each element in `x`.
 
 ### cosh(x, *, out=None)
 
@@ -205,7 +205,7 @@ Calculates an implementation-dependent approximation to the hyperbolic cosine fo
 
 #### Returns
 
--   **out**: an array containing the absolute value of each element in `x`.
+-   **out**: an array containing the hyperbolic cosine of each element in `x`.
 
 ### exp(x, *, out=None)
 
@@ -243,7 +243,7 @@ Calculates an implementation-dependent approximation to the natural logarithm fo
 
 #### Returns
 
--   **out**: an array containing the evaluated exponential function result for each element in `x`.
+-   **out**: an array containing the evaluated natural logarithm for each element in `x`.
 
 ### sin(x, *, out=None)
 
@@ -261,7 +261,7 @@ Calculates an implementation-dependent approximation to the sine for each elemen
 
 #### Returns
 
--   **out**: an array containing the absolute value of each element in `x`.
+-   **out**: an array containing the sine of each element in `x`.
 
 ### sinh(x, *, out=None)
 
@@ -280,7 +280,7 @@ Calculates an implementation-dependent approximation to the hyperbolic sine for
 
 #### Returns
 
--   **out**: an array containing the absolute value of each element in `x`.
+-   **out**: an array containing the hyperbolic sine of each element in `x`.
 
 ### sqrt(x, *, out=None)
 
@@ -292,6 +292,15 @@ Calculates an implementation-dependent approximation to the square root for each
 -   If `x_i` is `-0`, the result is `-0`.
 -   If `x_i` is `+infinity`, the result is `+infinity`.
 
+#### Parameters
+
+-   **x**: input array.
+-   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+
+#### Returns
+
+-   **out**: an array containing the square root of each element in `x`.
+
 ### tan(x, *, out=None)
 
 Calculates an implementation-dependent approximation to the tangent for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.
@@ -308,7 +317,7 @@ Calculates an implementation-dependent approximation to the tangent for each ele
 
 #### Returns
 
--   **out**: an array containing the absolute value of each element in `x`.
+-   **out**: an array containing the tangent of each element in `x`.
 
 ### tanh(x, *, out=None)
 
@@ -327,7 +336,7 @@ Calculates an implementation-dependent approximation to the hyperbolic tangent f
 
 #### Returns
 
--   **out**: an array containing the absolute value of each element in `x`.
+-   **out**: an array containing the hyperbolic tangent of each element in `x`.
 
 * * *
 

From f3d5cd6352b74941a45af5ab067133cf88dd55c4 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Thu, 30 Jul 2020 01:29:53 -0700
Subject: [PATCH 04/67] Add rounding functions

---
 spec/API_specification/functions.md | 65 ++++++++++++++++++++++++++++-
 1 file changed, 63 insertions(+), 2 deletions(-)

diff --git a/spec/API_specification/functions.md b/spec/API_specification/functions.md
index 88d1f43c9..13ac6f547 100644
--- a/spec/API_specification/functions.md
+++ b/spec/API_specification/functions.md
@@ -136,8 +136,8 @@ Calculates an implementation-dependent approximation to the inverse tangent for
 -   If `x_i` is `NaN`, the result is `NaN`.
 -   If `x_i` is `+0`, the result is `+0`.
 -   If `x_i` is `-0`, the result is `-0`.
--   If `x_i` is `+infinity`, the result is an implementation-dependent approximation to `+π/2`.
--   If `x_i` is `-infinity`, the result is an implementation-dependent approximation to `-π/2`.
+-   If `x_i` is `+infinity`, the result is an implementation-dependent approximation to `+π/2` (rounded).
+-   If `x_i` is `-infinity`, the result is an implementation-dependent approximation to `-π/2` (rounded).
 
 #### Parameters
 
@@ -169,6 +169,21 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic t
 
 -   **out**: an array containing the inverse hyperbolic tangent of each element in `x`.
 
+### ceil(x, *, out=None)
+
+Rounds each element `x_i` of the input array `x` to the smallest (i.e., closest to `-infinity`) integer-valued number that is not less than `x_i`.
+
+-   If `x_i` is already integer-valued, the result is `x_i`.
+
+#### Parameters
+
+-   **x**: input array.
+-   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+
+#### Returns
+
+-   **out**: an array containing the rounded result for each element in `x`.
+
 ### cos(x, *, out=None)
 
 Calculates an implementation-dependent approximation to the cosine for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.
@@ -226,6 +241,21 @@ Calculates an implementation-dependent approximation to the exponential function
 
 -   **out**: an array containing the evaluated exponential function result for each element in `x`.
 
+### floor(x, *, out=None)
+
+Rounds each element `x_i` of the input array `x` to the greatest (i.e., closest to `+infinity`) integer-valued number that is not greater than `x_i`.
+
+-   If `x_i` is already integer-valued, the result is `x_i`.
+
+#### Parameters
+
+-   **x**: input array.
+-   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+
+#### Returns
+
+-   **out**: an array containing the rounded result for each element in `x`.
+
 ### log(x, *, out=None)
 
 Calculates an implementation-dependent approximation to the natural logarithm for each element `x_i` of the input array `x`.
@@ -245,6 +275,22 @@ Calculates an implementation-dependent approximation to the natural logarithm fo
 
 -   **out**: an array containing the evaluated natural logarithm for each element in `x`.
 
+### round(x, *, out=None)
+
+Rounds each element `x_i` of the input array `x` to the nearest integer-valued number.
+
+-   If `x_i` is already integer-valued, the result is `x_i`.
+-   If two integers are equally close to `x_i`, the result is whichever integer is farthest from `0`.
+
+#### Parameters
+
+-   **x**: input array.
+-   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+
+#### Returns
+
+-   **out**: an array containing the rounded result for each element in `x`.
+
 ### sin(x, *, out=None)
 
 Calculates an implementation-dependent approximation to the sine for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.
@@ -338,6 +384,21 @@ Calculates an implementation-dependent approximation to the hyperbolic tangent f
 
 -   **out**: an array containing the hyperbolic tangent of each element in `x`.
 
+### trunc(x, *, out=None)
+
+Rounds each element `x_i` of the input array `x` to the integer-valued number that is closest to but no greater than `x_i`.
+
+-   If `x_i` is already integer-valued, the result is `x_i`.
+
+#### Parameters
+
+-   **x**: input array.
+-   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+
+#### Returns
+
+-   **out**: an array containing the rounded result for each element in `x`.
+
 * * *
 
 ## Addendum

From 5fba6f18e6903077eaf64f1ac519077b79659580 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Thu, 30 Jul 2020 01:38:30 -0700
Subject: [PATCH 05/67] Add links

---
 spec/API_specification/functions.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/spec/API_specification/functions.md b/spec/API_specification/functions.md
index 13ac6f547..4a780a15f 100644
--- a/spec/API_specification/functions.md
+++ b/spec/API_specification/functions.md
@@ -38,7 +38,7 @@ A conforming implementation of the array API standard must provide and support t
 
 <!-- NOTE: please keep the functions in alphabetical order -->
 
-### abs(x, *, out=None)
+### <a name="abs" href="#abs">#</a> abs(x, *, out=None)
 
 Calculates the absolute value for each element `x_i` of the input array `x` (i.e., the element-wise result has the same magnitude as the respective element in `x` but has positive sign).
 
@@ -55,7 +55,7 @@ Calculates the absolute value for each element `x_i` of the input array `x` (i.e
 
 -   **out**: an array containing the absolute value of each element in `x`.
 
-### acos(x, *, out=None)
+### <a name="acos" href="#acos">#</a> acos(x, *, out=None)
 
 Calculates an implementation-dependent approximation to the inverse cosine for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians and ranges from `+0` to `+π`.
 

From 0f90c8f2a13966a9bd70a4f9462e011f15e01afb Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Thu, 30 Jul 2020 01:41:02 -0700
Subject: [PATCH 06/67] Add heading links

---
 spec/API_specification/functions.md | 36 ++++++++++++++---------------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/spec/API_specification/functions.md b/spec/API_specification/functions.md
index 4a780a15f..328359512 100644
--- a/spec/API_specification/functions.md
+++ b/spec/API_specification/functions.md
@@ -73,7 +73,7 @@ Calculates an implementation-dependent approximation to the inverse cosine for e
 
 -   **out**: an array containing the inverse cosine of each element in `x`.
 
-### acosh(x, *, out=None)
+### <a name="acosh" href="#acosh">#</a> acosh(x, *, out=None)
 
 Calculates an implementation-dependent approximation to the inverse hyperbolic cosine for each element `x_i` of the input array `x`.
 
@@ -91,7 +91,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic c
 
 -   **out**: an array containing the inverse hyperbolic cosine of each element in `x`.
 
-### asin(x, *, out=None)
+### <a name="asin" href="#asin">#</a> asin(x, *, out=None)
 
 Calculates an implementation-dependent approximation to the inverse sine for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians and ranges from `-π/2` to `+π/2`.
 
@@ -110,7 +110,7 @@ Calculates an implementation-dependent approximation to the inverse sine for eac
 
 -   **out**: an array containing the inverse sine of each element in `x`.
 
-### asinh(x, *, out=None)
+### <a name="asinh" href="#asinh">#</a> asinh(x, *, out=None)
 
 Calculates an implementation-dependent approximation to the inverse hyperbolic sine for each element `x_i` in the input array `x`.
 
@@ -129,7 +129,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic s
 
 -   **out**: an array containing the inverse hyperbolic sine of each element in `x`.
 
-### atan(x, *, out=None)
+### <a name="atan" href="#atan">#</a> atan(x, *, out=None)
 
 Calculates an implementation-dependent approximation to the inverse tangent for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians and ranges from `-π/2` to `+π/2`.
 
@@ -148,7 +148,7 @@ Calculates an implementation-dependent approximation to the inverse tangent for
 
 -   **out**: an array containing the inverse tangent of each element in `x`.
 
-### atanh(x, *, out=None)
+### <a name="atanh" href="#atanh">#</a> atanh(x, *, out=None)
 
 Calculates an implementation-dependent approximation to the inverse hyperbolic tangent for each element `x_i` of the input array `x`.
 
@@ -169,7 +169,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic t
 
 -   **out**: an array containing the inverse hyperbolic tangent of each element in `x`.
 
-### ceil(x, *, out=None)
+### <a name="ceil" href="#ceil">#</a> ceil(x, *, out=None)
 
 Rounds each element `x_i` of the input array `x` to the smallest (i.e., closest to `-infinity`) integer-valued number that is not less than `x_i`.
 
@@ -184,7 +184,7 @@ Rounds each element `x_i` of the input array `x` to the smallest (i.e., closest
 
 -   **out**: an array containing the rounded result for each element in `x`.
 
-### cos(x, *, out=None)
+### <a name="cos" href="#cos">#</a> cos(x, *, out=None)
 
 Calculates an implementation-dependent approximation to the cosine for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.
 
@@ -203,7 +203,7 @@ Calculates an implementation-dependent approximation to the cosine for each elem
 
 -   **out**: an array containing the cosine of each element in `x`.
 
-### cosh(x, *, out=None)
+### <a name="cosh" href="#cosh">#</a> cosh(x, *, out=None)
 
 Calculates an implementation-dependent approximation to the hyperbolic cosine for each element `x_i` in the input array `x`.
 
@@ -222,7 +222,7 @@ Calculates an implementation-dependent approximation to the hyperbolic cosine fo
 
 -   **out**: an array containing the hyperbolic cosine of each element in `x`.
 
-### exp(x, *, out=None)
+### <a name="exp" href="#exp">#</a> exp(x, *, out=None)
 
 Calculates an implementation-dependent approximation to the exponential function for each element `x_i` of the input array `x` (`e` raised to the power of `x_i`, where `e` is the base of the natural logarithm).
 
@@ -241,7 +241,7 @@ Calculates an implementation-dependent approximation to the exponential function
 
 -   **out**: an array containing the evaluated exponential function result for each element in `x`.
 
-### floor(x, *, out=None)
+### <a name="floor" href="#floor">#</a> floor(x, *, out=None)
 
 Rounds each element `x_i` of the input array `x` to the greatest (i.e., closest to `+infinity`) integer-valued number that is not greater than `x_i`.
 
@@ -256,7 +256,7 @@ Rounds each element `x_i` of the input array `x` to the greatest (i.e., closest
 
 -   **out**: an array containing the rounded result for each element in `x`.
 
-### log(x, *, out=None)
+### <a name="log" href="#log">#</a> log(x, *, out=None)
 
 Calculates an implementation-dependent approximation to the natural logarithm for each element `x_i` of the input array `x`.
 
@@ -275,7 +275,7 @@ Calculates an implementation-dependent approximation to the natural logarithm fo
 
 -   **out**: an array containing the evaluated natural logarithm for each element in `x`.
 
-### round(x, *, out=None)
+### <a name="round" href="#round">#</a> round(x, *, out=None)
 
 Rounds each element `x_i` of the input array `x` to the nearest integer-valued number.
 
@@ -291,7 +291,7 @@ Rounds each element `x_i` of the input array `x` to the nearest integer-valued n
 
 -   **out**: an array containing the rounded result for each element in `x`.
 
-### sin(x, *, out=None)
+### <a name="sin" href="#sin">#</a> sin(x, *, out=None)
 
 Calculates an implementation-dependent approximation to the sine for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.
 
@@ -309,7 +309,7 @@ Calculates an implementation-dependent approximation to the sine for each elemen
 
 -   **out**: an array containing the sine of each element in `x`.
 
-### sinh(x, *, out=None)
+### <a name="sinh" href="#sinh">#</a> sinh(x, *, out=None)
 
 Calculates an implementation-dependent approximation to the hyperbolic sine for each element `x_i` of the input array `x`.
 
@@ -328,7 +328,7 @@ Calculates an implementation-dependent approximation to the hyperbolic sine for
 
 -   **out**: an array containing the hyperbolic sine of each element in `x`.
 
-### sqrt(x, *, out=None)
+### <a name="sqrt" href="#sqrt">#</a> sqrt(x, *, out=None)
 
 Calculates an implementation-dependent approximation to the square root for each element `x_i` of the input array `x`.
 
@@ -347,7 +347,7 @@ Calculates an implementation-dependent approximation to the square root for each
 
 -   **out**: an array containing the square root of each element in `x`.
 
-### tan(x, *, out=None)
+### <a name="tan" href="#tan">#</a> tan(x, *, out=None)
 
 Calculates an implementation-dependent approximation to the tangent for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.
 
@@ -365,7 +365,7 @@ Calculates an implementation-dependent approximation to the tangent for each ele
 
 -   **out**: an array containing the tangent of each element in `x`.
 
-### tanh(x, *, out=None)
+### <a name="tanh" href="#tanh">#</a> tanh(x, *, out=None)
 
 Calculates an implementation-dependent approximation to the hyperbolic tangent for each element `x_i` of the input array `x`.
 
@@ -384,7 +384,7 @@ Calculates an implementation-dependent approximation to the hyperbolic tangent f
 
 -   **out**: an array containing the hyperbolic tangent of each element in `x`.
 
-### trunc(x, *, out=None)
+### <a name="trunc" href="#trunc">#</a> trunc(x, *, out=None)
 
 Rounds each element `x_i` of the input array `x` to the integer-valued number that is closest to but no greater than `x_i`.
 

From 13e375866fedb023287d13bae9846d5c4fb8a30b Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Thu, 30 Jul 2020 01:43:37 -0700
Subject: [PATCH 07/67] Move notes up in document

---
 spec/API_specification/functions.md | 16 ++++++----------
 1 file changed, 6 insertions(+), 10 deletions(-)

diff --git a/spec/API_specification/functions.md b/spec/API_specification/functions.md
index 328359512..9b3a2b06f 100644
--- a/spec/API_specification/functions.md
+++ b/spec/API_specification/functions.md
@@ -34,7 +34,12 @@ a tuple of `N` non-negative integers that specify the sizes of each dimension an
 
 ## Functions
 
-A conforming implementation of the array API standard must provide and support the following functions.
+A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions:
+
+-   Optional arguments must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments.
+-   The `out` keyword argument must be a tuple with one entry per output.
+-   If `out` is not provided or is `None` (the default), an uninitialized return array must be created for each output.
+-   Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.
 
 <!-- NOTE: please keep the functions in alphabetical order -->
 
@@ -398,12 +403,3 @@ Rounds each element `x_i` of the input array `x` to the integer-valued number th
 #### Returns
 
 -   **out**: an array containing the rounded result for each element in `x`.
-
-* * *
-
-## Addendum
-
--   Optional arguments must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments.
--   The `out` keyword argument must be a tuple with one entry per output.
--   If `out` is not provided or is `None` (the default), an uninitialized return array must be created for each output.
--   Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.
\ No newline at end of file

From 3b512d9cfa9227ab2aaf3e69c69ee272c652635b Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Thu, 30 Jul 2020 01:56:30 -0700
Subject: [PATCH 08/67] Add arithmetic operations

---
 spec/API_specification/functions.md | 66 ++++++++++++++++++++++++++++-
 1 file changed, 65 insertions(+), 1 deletion(-)

diff --git a/spec/API_specification/functions.md b/spec/API_specification/functions.md
index 9b3a2b06f..4a5bf569b 100644
--- a/spec/API_specification/functions.md
+++ b/spec/API_specification/functions.md
@@ -34,7 +34,7 @@ a tuple of `N` non-negative integers that specify the sizes of each dimension an
 
 ## Functions
 
-A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions:
+A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions.
 
 -   Optional arguments must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments.
 -   The `out` keyword argument must be a tuple with one entry per output.
@@ -96,6 +96,22 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic c
 
 -   **out**: an array containing the inverse hyperbolic cosine of each element in `x`.
 
+### <a name="add" href="#add">#</a> add(x1, x2, *, out=None)
+
+Calculates the sum for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`.
+
+-   If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`.
+
+#### Parameters
+
+-   **x1**: input array.
+-   **x2**: input array.
+-   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+
+#### Returns
+
+-   **out**: an array containing the element-wise sums.
+
 ### <a name="asin" href="#asin">#</a> asin(x, *, out=None)
 
 Calculates an implementation-dependent approximation to the inverse sine for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians and ranges from `-π/2` to `+π/2`.
@@ -227,6 +243,22 @@ Calculates an implementation-dependent approximation to the hyperbolic cosine fo
 
 -   **out**: an array containing the hyperbolic cosine of each element in `x`.
 
+### <a name="divide" href="#divide">#</a> divide(x1, x2, *, out=None)
+
+Calculates the division for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`.
+
+-   If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`.
+
+#### Parameters
+
+-   **x1**: dividend input array.
+-   **x2**: divisor input array.
+-   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+
+#### Returns
+
+-   **out**: an array containing the element-wise results.
+
 ### <a name="exp" href="#exp">#</a> exp(x, *, out=None)
 
 Calculates an implementation-dependent approximation to the exponential function for each element `x_i` of the input array `x` (`e` raised to the power of `x_i`, where `e` is the base of the natural logarithm).
@@ -280,6 +312,22 @@ Calculates an implementation-dependent approximation to the natural logarithm fo
 
 -   **out**: an array containing the evaluated natural logarithm for each element in `x`.
 
+### <a name="multiply" href="#multiply">#</a> multiply(x1, x2, *, out=None)
+
+Calculates the product for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`.
+
+-   If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`.
+
+#### Parameters
+
+-   **x1**: input array.
+-   **x2**: input array.
+-   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+
+#### Returns
+
+-   **out**: an array containing the element-wise products.
+
 ### <a name="round" href="#round">#</a> round(x, *, out=None)
 
 Rounds each element `x_i` of the input array `x` to the nearest integer-valued number.
@@ -352,6 +400,22 @@ Calculates an implementation-dependent approximation to the square root for each
 
 -   **out**: an array containing the square root of each element in `x`.
 
+### <a name="subtract" href="#subtract">#</a> subtract(x1, x2, *, out=None)
+
+Calculates the difference for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`.
+
+-   If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`.
+
+#### Parameters
+
+-   **x1**: input array.
+-   **x2**: input array.
+-   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+
+#### Returns
+
+-   **out**: an array containing the element-wise differences.
+
 ### <a name="tan" href="#tan">#</a> tan(x, *, out=None)
 
 Calculates an implementation-dependent approximation to the tangent for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.

From 4491793d7f2532b80f901be2f74880d8390b3bf8 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Thu, 30 Jul 2020 13:06:35 -0700
Subject: [PATCH 09/67] Add domain and codomain

---
 spec/API_specification/functions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/API_specification/functions.md b/spec/API_specification/functions.md
index 4a5bf569b..e4d08d25f 100644
--- a/spec/API_specification/functions.md
+++ b/spec/API_specification/functions.md
@@ -62,7 +62,7 @@ Calculates the absolute value for each element `x_i` of the input array `x` (i.e
 
 ### <a name="acos" href="#acos">#</a> acos(x, *, out=None)
 
-Calculates an implementation-dependent approximation to the inverse cosine for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians and ranges from `+0` to `+π`.
+Calculates an implementation-dependent approximation to the inverse cosine, having domain `[-1,+1]` and codomain `[+0, +π]`, for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians.
 
 -   If `x_i` is `NaN`, the result is `NaN`.
 -   If `x_i` is greater than `1`, the result is `NaN`.

From 668e9e2a75886217ebc2abad6f09b89a3c7ff2cc Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Thu, 30 Jul 2020 13:10:55 -0700
Subject: [PATCH 10/67] Make positional-parameters positional-only

Based on discussion here: https://github.com/pydata-apis/array-api/issues/8#issuecomment-666600012
---
 spec/API_specification/functions.md | 53 +++++++++++++++--------------
 1 file changed, 27 insertions(+), 26 deletions(-)

diff --git a/spec/API_specification/functions.md b/spec/API_specification/functions.md
index e4d08d25f..ba0aee6db 100644
--- a/spec/API_specification/functions.md
+++ b/spec/API_specification/functions.md
@@ -36,14 +36,15 @@ a tuple of `N` non-negative integers that specify the sizes of each dimension an
 
 A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions.
 
--   Optional arguments must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments.
--   The `out` keyword argument must be a tuple with one entry per output.
+-   Positional parameters must be [positional-only](https://www.python.org/dev/peps/pep-0570/) parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order.
+-   Optional parameters must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments.
+-   An `out` keyword argument must be a tuple with one entry per output.
 -   If `out` is not provided or is `None` (the default), an uninitialized return array must be created for each output.
 -   Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.
 
 <!-- NOTE: please keep the functions in alphabetical order -->
 
-### <a name="abs" href="#abs">#</a> abs(x, *, out=None)
+### <a name="abs" href="#abs">#</a> abs(x, /, *, out=None)
 
 Calculates the absolute value for each element `x_i` of the input array `x` (i.e., the element-wise result has the same magnitude as the respective element in `x` but has positive sign).
 
@@ -60,7 +61,7 @@ Calculates the absolute value for each element `x_i` of the input array `x` (i.e
 
 -   **out**: an array containing the absolute value of each element in `x`.
 
-### <a name="acos" href="#acos">#</a> acos(x, *, out=None)
+### <a name="acos" href="#acos">#</a> acos(x, /, *, out=None)
 
 Calculates an implementation-dependent approximation to the inverse cosine, having domain `[-1,+1]` and codomain `[+0, +π]`, for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians.
 
@@ -78,7 +79,7 @@ Calculates an implementation-dependent approximation to the inverse cosine, havi
 
 -   **out**: an array containing the inverse cosine of each element in `x`.
 
-### <a name="acosh" href="#acosh">#</a> acosh(x, *, out=None)
+### <a name="acosh" href="#acosh">#</a> acosh(x, /, *, out=None)
 
 Calculates an implementation-dependent approximation to the inverse hyperbolic cosine for each element `x_i` of the input array `x`.
 
@@ -96,7 +97,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic c
 
 -   **out**: an array containing the inverse hyperbolic cosine of each element in `x`.
 
-### <a name="add" href="#add">#</a> add(x1, x2, *, out=None)
+### <a name="add" href="#add">#</a> add(x1, x2, /, *, out=None)
 
 Calculates the sum for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`.
 
@@ -112,7 +113,7 @@ Calculates the sum for each element `x1_i` of the input array `x1` with the resp
 
 -   **out**: an array containing the element-wise sums.
 
-### <a name="asin" href="#asin">#</a> asin(x, *, out=None)
+### <a name="asin" href="#asin">#</a> asin(x, /, *, out=None)
 
 Calculates an implementation-dependent approximation to the inverse sine for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians and ranges from `-π/2` to `+π/2`.
 
@@ -131,7 +132,7 @@ Calculates an implementation-dependent approximation to the inverse sine for eac
 
 -   **out**: an array containing the inverse sine of each element in `x`.
 
-### <a name="asinh" href="#asinh">#</a> asinh(x, *, out=None)
+### <a name="asinh" href="#asinh">#</a> asinh(x, /, *, out=None)
 
 Calculates an implementation-dependent approximation to the inverse hyperbolic sine for each element `x_i` in the input array `x`.
 
@@ -150,7 +151,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic s
 
 -   **out**: an array containing the inverse hyperbolic sine of each element in `x`.
 
-### <a name="atan" href="#atan">#</a> atan(x, *, out=None)
+### <a name="atan" href="#atan">#</a> atan(x, /, *, out=None)
 
 Calculates an implementation-dependent approximation to the inverse tangent for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians and ranges from `-π/2` to `+π/2`.
 
@@ -169,7 +170,7 @@ Calculates an implementation-dependent approximation to the inverse tangent for
 
 -   **out**: an array containing the inverse tangent of each element in `x`.
 
-### <a name="atanh" href="#atanh">#</a> atanh(x, *, out=None)
+### <a name="atanh" href="#atanh">#</a> atanh(x, /, *, out=None)
 
 Calculates an implementation-dependent approximation to the inverse hyperbolic tangent for each element `x_i` of the input array `x`.
 
@@ -190,7 +191,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic t
 
 -   **out**: an array containing the inverse hyperbolic tangent of each element in `x`.
 
-### <a name="ceil" href="#ceil">#</a> ceil(x, *, out=None)
+### <a name="ceil" href="#ceil">#</a> ceil(x, /, *, out=None)
 
 Rounds each element `x_i` of the input array `x` to the smallest (i.e., closest to `-infinity`) integer-valued number that is not less than `x_i`.
 
@@ -205,7 +206,7 @@ Rounds each element `x_i` of the input array `x` to the smallest (i.e., closest
 
 -   **out**: an array containing the rounded result for each element in `x`.
 
-### <a name="cos" href="#cos">#</a> cos(x, *, out=None)
+### <a name="cos" href="#cos">#</a> cos(x, /, *, out=None)
 
 Calculates an implementation-dependent approximation to the cosine for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.
 
@@ -224,7 +225,7 @@ Calculates an implementation-dependent approximation to the cosine for each elem
 
 -   **out**: an array containing the cosine of each element in `x`.
 
-### <a name="cosh" href="#cosh">#</a> cosh(x, *, out=None)
+### <a name="cosh" href="#cosh">#</a> cosh(x, /, *, out=None)
 
 Calculates an implementation-dependent approximation to the hyperbolic cosine for each element `x_i` in the input array `x`.
 
@@ -243,7 +244,7 @@ Calculates an implementation-dependent approximation to the hyperbolic cosine fo
 
 -   **out**: an array containing the hyperbolic cosine of each element in `x`.
 
-### <a name="divide" href="#divide">#</a> divide(x1, x2, *, out=None)
+### <a name="divide" href="#divide">#</a> divide(x1, x2, /, *, out=None)
 
 Calculates the division for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`.
 
@@ -259,7 +260,7 @@ Calculates the division for each element `x1_i` of the input array `x1` with the
 
 -   **out**: an array containing the element-wise results.
 
-### <a name="exp" href="#exp">#</a> exp(x, *, out=None)
+### <a name="exp" href="#exp">#</a> exp(x, /, *, out=None)
 
 Calculates an implementation-dependent approximation to the exponential function for each element `x_i` of the input array `x` (`e` raised to the power of `x_i`, where `e` is the base of the natural logarithm).
 
@@ -278,7 +279,7 @@ Calculates an implementation-dependent approximation to the exponential function
 
 -   **out**: an array containing the evaluated exponential function result for each element in `x`.
 
-### <a name="floor" href="#floor">#</a> floor(x, *, out=None)
+### <a name="floor" href="#floor">#</a> floor(x, /, *, out=None)
 
 Rounds each element `x_i` of the input array `x` to the greatest (i.e., closest to `+infinity`) integer-valued number that is not greater than `x_i`.
 
@@ -293,7 +294,7 @@ Rounds each element `x_i` of the input array `x` to the greatest (i.e., closest
 
 -   **out**: an array containing the rounded result for each element in `x`.
 
-### <a name="log" href="#log">#</a> log(x, *, out=None)
+### <a name="log" href="#log">#</a> log(x, /, *, out=None)
 
 Calculates an implementation-dependent approximation to the natural logarithm for each element `x_i` of the input array `x`.
 
@@ -312,7 +313,7 @@ Calculates an implementation-dependent approximation to the natural logarithm fo
 
 -   **out**: an array containing the evaluated natural logarithm for each element in `x`.
 
-### <a name="multiply" href="#multiply">#</a> multiply(x1, x2, *, out=None)
+### <a name="multiply" href="#multiply">#</a> multiply(x1, x2, /, *, out=None)
 
 Calculates the product for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`.
 
@@ -328,7 +329,7 @@ Calculates the product for each element `x1_i` of the input array `x1` with the
 
 -   **out**: an array containing the element-wise products.
 
-### <a name="round" href="#round">#</a> round(x, *, out=None)
+### <a name="round" href="#round">#</a> round(x, /, *, out=None)
 
 Rounds each element `x_i` of the input array `x` to the nearest integer-valued number.
 
@@ -344,7 +345,7 @@ Rounds each element `x_i` of the input array `x` to the nearest integer-valued n
 
 -   **out**: an array containing the rounded result for each element in `x`.
 
-### <a name="sin" href="#sin">#</a> sin(x, *, out=None)
+### <a name="sin" href="#sin">#</a> sin(x, /, *, out=None)
 
 Calculates an implementation-dependent approximation to the sine for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.
 
@@ -362,7 +363,7 @@ Calculates an implementation-dependent approximation to the sine for each elemen
 
 -   **out**: an array containing the sine of each element in `x`.
 
-### <a name="sinh" href="#sinh">#</a> sinh(x, *, out=None)
+### <a name="sinh" href="#sinh">#</a> sinh(x, /, *, out=None)
 
 Calculates an implementation-dependent approximation to the hyperbolic sine for each element `x_i` of the input array `x`.
 
@@ -381,7 +382,7 @@ Calculates an implementation-dependent approximation to the hyperbolic sine for
 
 -   **out**: an array containing the hyperbolic sine of each element in `x`.
 
-### <a name="sqrt" href="#sqrt">#</a> sqrt(x, *, out=None)
+### <a name="sqrt" href="#sqrt">#</a> sqrt(x, /, *, out=None)
 
 Calculates an implementation-dependent approximation to the square root for each element `x_i` of the input array `x`.
 
@@ -400,7 +401,7 @@ Calculates an implementation-dependent approximation to the square root for each
 
 -   **out**: an array containing the square root of each element in `x`.
 
-### <a name="subtract" href="#subtract">#</a> subtract(x1, x2, *, out=None)
+### <a name="subtract" href="#subtract">#</a> subtract(x1, x2, /, *, out=None)
 
 Calculates the difference for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`.
 
@@ -416,7 +417,7 @@ Calculates the difference for each element `x1_i` of the input array `x1` with t
 
 -   **out**: an array containing the element-wise differences.
 
-### <a name="tan" href="#tan">#</a> tan(x, *, out=None)
+### <a name="tan" href="#tan">#</a> tan(x, /, *, out=None)
 
 Calculates an implementation-dependent approximation to the tangent for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.
 
@@ -434,7 +435,7 @@ Calculates an implementation-dependent approximation to the tangent for each ele
 
 -   **out**: an array containing the tangent of each element in `x`.
 
-### <a name="tanh" href="#tanh">#</a> tanh(x, *, out=None)
+### <a name="tanh" href="#tanh">#</a> tanh(x, /, *, out=None)
 
 Calculates an implementation-dependent approximation to the hyperbolic tangent for each element `x_i` of the input array `x`.
 
@@ -453,7 +454,7 @@ Calculates an implementation-dependent approximation to the hyperbolic tangent f
 
 -   **out**: an array containing the hyperbolic tangent of each element in `x`.
 
-### <a name="trunc" href="#trunc">#</a> trunc(x, *, out=None)
+### <a name="trunc" href="#trunc">#</a> trunc(x, /, *, out=None)
 
 Rounds each element `x_i` of the input array `x` to the integer-valued number that is closest to but no greater than `x_i`.
 

From ddca794852f203604d8bada95a2fd621c6b4b1af Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Thu, 30 Jul 2020 13:52:41 -0700
Subject: [PATCH 11/67] Add domains and codomains

---
 spec/API_specification/functions.md | 48 ++++++++++++++---------------
 1 file changed, 24 insertions(+), 24 deletions(-)

diff --git a/spec/API_specification/functions.md b/spec/API_specification/functions.md
index ba0aee6db..067105632 100644
--- a/spec/API_specification/functions.md
+++ b/spec/API_specification/functions.md
@@ -63,7 +63,7 @@ Calculates the absolute value for each element `x_i` of the input array `x` (i.e
 
 ### <a name="acos" href="#acos">#</a> acos(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the inverse cosine, having domain `[-1,+1]` and codomain `[+0, +π]`, for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians.
+Calculates an implementation-dependent approximation of the principal value of the inverse cosine, having domain `[-1,+1]` and codomain `[+0, +π]`, for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians.
 
 -   If `x_i` is `NaN`, the result is `NaN`.
 -   If `x_i` is greater than `1`, the result is `NaN`.
@@ -81,7 +81,7 @@ Calculates an implementation-dependent approximation to the inverse cosine, havi
 
 ### <a name="acosh" href="#acosh">#</a> acosh(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the inverse hyperbolic cosine for each element `x_i` of the input array `x`.
+Calculates an implementation-dependent approximation to the inverse hyperbolic cosine, having domain `[+1, +infinity]` and codomain `[+0, +infinity]`, for each element `x_i` of the input array `x`.
 
 -   If `x_i` is `NaN`, the result is `NaN`.
 -   If `x_i` is less than `1`, the result is `NaN`.
@@ -90,7 +90,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic c
 
 #### Parameters
 
--   **x**: input array.
+-   **x**: input array whose elements each represent the area of a hyperbolic sector.
 -   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
@@ -115,7 +115,7 @@ Calculates the sum for each element `x1_i` of the input array `x1` with the resp
 
 ### <a name="asin" href="#asin">#</a> asin(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the inverse sine for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians and ranges from `-π/2` to `+π/2`.
+Calculates an implementation-dependent approximation of the principal value of the inverse sine, having domain `[-1, +1]` and codomain `[-π/2, +π/2]` for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians.
 
 -   If `x_i` is `NaN`, the result is `NaN`.
 -   If `x_i` is greater than `1`, the result is `NaN`.
@@ -134,7 +134,7 @@ Calculates an implementation-dependent approximation to the inverse sine for eac
 
 ### <a name="asinh" href="#asinh">#</a> asinh(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the inverse hyperbolic sine for each element `x_i` in the input array `x`.
+Calculates an implementation-dependent approximation to the inverse hyperbolic sine, having domain `[-infinity, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` in the input array `x`.
 
 -   If `x_i` is `NaN`, the result is `NaN`.
 -   If `x_i` is `+0`, the result is `+0`.
@@ -144,7 +144,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic s
 
 #### Parameters
 
--   **x**: input array.
+-   **x**: input array whose elements each represent the area of a hyperbolic sector.
 -   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
@@ -153,7 +153,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic s
 
 ### <a name="atan" href="#atan">#</a> atan(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the inverse tangent for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians and ranges from `-π/2` to `+π/2`.
+Calculates an implementation-dependent approximation of the principal value of the inverse tangent, having domain `[-infinity, +infinity]` and codomain `[-π/2, +π/2]`, for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians.
 
 -   If `x_i` is `NaN`, the result is `NaN`.
 -   If `x_i` is `+0`, the result is `+0`.
@@ -172,7 +172,7 @@ Calculates an implementation-dependent approximation to the inverse tangent for
 
 ### <a name="atanh" href="#atanh">#</a> atanh(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the inverse hyperbolic tangent for each element `x_i` of the input array `x`.
+Calculates an implementation-dependent approximation to the inverse hyperbolic tangent, having domain `[-1, +1]` and codomain `[-infinity, +infinity]`, for each element `x_i` of the input array `x`.
 
 -   If `x_i` is `NaN`, the result is `NaN`.
 -   If `x_i` is less than `-1`, the result is `NaN`.
@@ -184,7 +184,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic t
 
 #### Parameters
 
--   **x**: input array.
+-   **x**: input array whose elements each represent the area of a hyperbolic sector.
 -   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
@@ -208,7 +208,7 @@ Rounds each element `x_i` of the input array `x` to the smallest (i.e., closest
 
 ### <a name="cos" href="#cos">#</a> cos(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the cosine for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.
+Calculates an implementation-dependent approximation to the cosine, having domain `(-infinity, +infinity)` and codomain `[-1, +1]`, for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.
 
 -   If `x_i` is `NaN`, the result is `NaN`.
 -   If `x_i` is `+0`, the result is `1`.
@@ -218,7 +218,7 @@ Calculates an implementation-dependent approximation to the cosine for each elem
 
 #### Parameters
 
--   **x**: input array.
+-   **x**: input array whose elements are each expressed in radians.
 -   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
@@ -227,7 +227,7 @@ Calculates an implementation-dependent approximation to the cosine for each elem
 
 ### <a name="cosh" href="#cosh">#</a> cosh(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the hyperbolic cosine for each element `x_i` in the input array `x`.
+Calculates an implementation-dependent approximation to the hyperbolic cosine, having domain `[-infinity, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` in the input array `x`.
 
 -   If `x_i` is `NaN`, the result is `NaN`.
 -   If `x_i` is `+0`, the result is `1`.
@@ -237,7 +237,7 @@ Calculates an implementation-dependent approximation to the hyperbolic cosine fo
 
 #### Parameters
 
--   **x**: input array.
+-   **x**: input array whose elements each represent a hyperbolic angle.
 -   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
@@ -262,7 +262,7 @@ Calculates the division for each element `x1_i` of the input array `x1` with the
 
 ### <a name="exp" href="#exp">#</a> exp(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the exponential function for each element `x_i` of the input array `x` (`e` raised to the power of `x_i`, where `e` is the base of the natural logarithm).
+Calculates an implementation-dependent approximation to the exponential function, having domain `[-infinity, +infinity]` and codomain `[+0, +infinity]`, for each element `x_i` of the input array `x` (`e` raised to the power of `x_i`, where `e` is the base of the natural logarithm).
 
 -   If `x_i` is `NaN`, the result is `NaN`.
 -   If `x_i` is `+0`, the result is `1`.
@@ -296,7 +296,7 @@ Rounds each element `x_i` of the input array `x` to the greatest (i.e., closest
 
 ### <a name="log" href="#log">#</a> log(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the natural logarithm for each element `x_i` of the input array `x`.
+Calculates an implementation-dependent approximation to the natural (base `e`) logarithm, having domain `[0, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` of the input array `x`.
 
 -   If `x_i` is `NaN`, the result is `NaN`.
 -   If `x_i` is less than `0`, the result is `NaN`.
@@ -347,7 +347,7 @@ Rounds each element `x_i` of the input array `x` to the nearest integer-valued n
 
 ### <a name="sin" href="#sin">#</a> sin(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the sine for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.
+Calculates an implementation-dependent approximation to the sine, having domain `(-infinity, +infinity)` and codomain `[-1, +1]`, for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.
 
 -   If `x_i` is `NaN`, the result is `NaN`.
 -   If `x_i` is `+0`, the result is `+0`.
@@ -356,7 +356,7 @@ Calculates an implementation-dependent approximation to the sine for each elemen
 
 #### Parameters
 
--   **x**: input array.
+-   **x**: input array whose elements are each expressed in radians.
 -   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
@@ -365,7 +365,7 @@ Calculates an implementation-dependent approximation to the sine for each elemen
 
 ### <a name="sinh" href="#sinh">#</a> sinh(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the hyperbolic sine for each element `x_i` of the input array `x`.
+Calculates an implementation-dependent approximation to the hyperbolic sine, having domain `[-infinity, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` of the input array `x`.
 
 -   If `x_i` is `NaN`, the result is `NaN`.
 -   If `x_i` is `+0`, the result is `+0`.
@@ -375,7 +375,7 @@ Calculates an implementation-dependent approximation to the hyperbolic sine for
 
 #### Parameters
 
--   **x**: input array.
+-   **x**: input array whose elements each represent a hyperbolic angle.
 -   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
@@ -384,7 +384,7 @@ Calculates an implementation-dependent approximation to the hyperbolic sine for
 
 ### <a name="sqrt" href="#sqrt">#</a> sqrt(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the square root for each element `x_i` of the input array `x`.
+Calculates the square root, having domain `[0, +infinity]` and codomain `[0, +infinity]`, for each element `x_i` of the input array `x`. After rounding, each result should be indistinguishable from the infinitely precise result (as required by IEEE 754).
 
 -   If `x_i` is `NaN`, the result is `NaN`.
 -   If `x_i` is less than `0`, the result is `NaN`.
@@ -419,7 +419,7 @@ Calculates the difference for each element `x1_i` of the input array `x1` with t
 
 ### <a name="tan" href="#tan">#</a> tan(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the tangent for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.
+Calculates an implementation-dependent approximation to the tangent, having domain `(-infinity, +infinity)` and codomain `(-infinity, +infinity)`, for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.
 
 -   If `x_i` is `NaN`, the result is `NaN`.
 -   If `x_i` is `+0`, the result is `+0`.
@@ -428,7 +428,7 @@ Calculates an implementation-dependent approximation to the tangent for each ele
 
 #### Parameters
 
--   **x**: input array.
+-   **x**: input array whose elements are each expressed in radians.
 -   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
@@ -437,7 +437,7 @@ Calculates an implementation-dependent approximation to the tangent for each ele
 
 ### <a name="tanh" href="#tanh">#</a> tanh(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the hyperbolic tangent for each element `x_i` of the input array `x`.
+Calculates an implementation-dependent approximation to the hyperbolic tangent, having domain `[-infinity, +infinity]` and codomain `[-1, +1]`, for each element `x_i` of the input array `x`.
 
 -   If `x_i` is `NaN`, the result is `NaN`.
 -   If `x_i` is `+0`, the result is `+0`.
@@ -447,7 +447,7 @@ Calculates an implementation-dependent approximation to the hyperbolic tangent f
 
 #### Parameters
 
--   **x**: input array.
+-   **x**: input array whose elements each represent a hyperbolic angle.
 -   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns

From d7df3fd0edeab24444b79b8db6e4c4d2cbe899a8 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Thu, 30 Jul 2020 14:09:32 -0700
Subject: [PATCH 12/67] Rename file and add definition

---
 .../{functions.md => elementwise_functions.md}            | 8 ++++++--
 spec/API_specification/index.rst                          | 2 +-
 2 files changed, 7 insertions(+), 3 deletions(-)
 rename spec/API_specification/{functions.md => elementwise_functions.md} (98%)

diff --git a/spec/API_specification/functions.md b/spec/API_specification/elementwise_functions.md
similarity index 98%
rename from spec/API_specification/functions.md
rename to spec/API_specification/elementwise_functions.md
index 067105632..6f520fe6b 100644
--- a/spec/API_specification/functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -1,6 +1,6 @@
-# Functions
+# Element-wise Functions
 
-> Array API function specification.
+> Array API specification for element-wise functions.
 
 ## Conformance
 
@@ -30,6 +30,10 @@ a (usually fixed-size) multidimensional container of items of the same type and
 
 a tuple of `N` non-negative integers that specify the sizes of each dimension and where `N` corresponds to the number of dimensions.
 
+### element-wise
+
+an operation performed element-by-element, in which individual array elements are considered in isolation and independently of surrounding array elements.
+
 * * *
 
 ## Functions
diff --git a/spec/API_specification/index.rst b/spec/API_specification/index.rst
index b4bfa0a23..7035c369b 100644
--- a/spec/API_specification/index.rst
+++ b/spec/API_specification/index.rst
@@ -6,6 +6,6 @@ API specification
    :maxdepth: 1
 
    array_object
-   functions
+   elementwise_functions
    indexing
    casting

From c7079108890dbf14fa5c3a21eb09d542397d8daf Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Thu, 30 Jul 2020 15:17:52 -0700
Subject: [PATCH 13/67] Experiment with subscripts

---
 spec/API_specification/elementwise_functions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index 6f520fe6b..a7e40117a 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -50,7 +50,7 @@ A conforming implementation of the array API standard must provide and support t
 
 ### <a name="abs" href="#abs">#</a> abs(x, /, *, out=None)
 
-Calculates the absolute value for each element `x_i` of the input array `x` (i.e., the element-wise result has the same magnitude as the respective element in `x` but has positive sign).
+Calculates the absolute value for each element `xᵢ` of the input array `x` (i.e., the element-wise result has the same magnitude as the respective element in `x` but has positive sign).
 
 -   If `x_i` is `NaN`, the result is `NaN`.
 -   If `x_i` is `-0`, the result is `+0`.

From f5de1c4a35ea729f335bcda9948f5f95d98a0710 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Thu, 30 Jul 2020 15:18:49 -0700
Subject: [PATCH 14/67] Experiment with subscripts

---
 spec/API_specification/elementwise_functions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index a7e40117a..1f21c852e 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -52,7 +52,7 @@ A conforming implementation of the array API standard must provide and support t
 
 Calculates the absolute value for each element `xᵢ` of the input array `x` (i.e., the element-wise result has the same magnitude as the respective element in `x` but has positive sign).
 
--   If `x_i` is `NaN`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
 -   If `x_i` is `-0`, the result is `+0`.
 -   If `x_i` is `-infinity`, the result is `+infinity`.
 

From 6e2d1f20fc88381c86ba9f76b9834410f5cae294 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Thu, 30 Jul 2020 15:20:42 -0700
Subject: [PATCH 15/67] Use HTML subscripts

---
 .../elementwise_functions.md                  | 216 +++++++++---------
 1 file changed, 108 insertions(+), 108 deletions(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index 1f21c852e..c775a7396 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -50,11 +50,11 @@ A conforming implementation of the array API standard must provide and support t
 
 ### <a name="abs" href="#abs">#</a> abs(x, /, *, out=None)
 
-Calculates the absolute value for each element `xᵢ` of the input array `x` (i.e., the element-wise result has the same magnitude as the respective element in `x` but has positive sign).
+Calculates the absolute value for each element <code>x<sub>i</sub></code> of the input array `x` (i.e., the element-wise result has the same magnitude as the respective element in `x` but has positive sign).
 
 -   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
--   If `x_i` is `-0`, the result is `+0`.
--   If `x_i` is `-infinity`, the result is `+infinity`.
+-   If <code>x<sub>i</sub></code> is `-0`, the result is `+0`.
+-   If <code>x<sub>i</sub></code> is `-infinity`, the result is `+infinity`.
 
 #### Parameters
 
@@ -67,12 +67,12 @@ Calculates the absolute value for each element `xᵢ` of the input array `x` (i.
 
 ### <a name="acos" href="#acos">#</a> acos(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation of the principal value of the inverse cosine, having domain `[-1,+1]` and codomain `[+0, +π]`, for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians.
+Calculates an implementation-dependent approximation of the principal value of the inverse cosine, having domain `[-1, +1]` and codomain `[+0, +π]`, for each element <code>x<sub>i</sub></code> of the input array `x`. Each element-wise result is expressed in radians.
 
--   If `x_i` is `NaN`, the result is `NaN`.
--   If `x_i` is greater than `1`, the result is `NaN`.
--   If `x_i` is less than `-1`, the result is `NaN`.
--   If `x_i` is exactly `1`, the result is `+0`.
+-   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is greater than `1`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is less than `-1`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is exactly `1`, the result is `+0`.
 
 #### Parameters
 
@@ -85,12 +85,12 @@ Calculates an implementation-dependent approximation of the principal value of t
 
 ### <a name="acosh" href="#acosh">#</a> acosh(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the inverse hyperbolic cosine, having domain `[+1, +infinity]` and codomain `[+0, +infinity]`, for each element `x_i` of the input array `x`.
+Calculates an implementation-dependent approximation to the inverse hyperbolic cosine, having domain `[+1, +infinity]` and codomain `[+0, +infinity]`, for each element <code>x<sub>i</sub></code> of the input array `x`.
 
--   If `x_i` is `NaN`, the result is `NaN`.
--   If `x_i` is less than `1`, the result is `NaN`.
--   If `x_i` is `1`, the result is `+0`.
--   If `x_i` is `+infinity`, the result is `+infinity`.
+-   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is less than `1`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is `1`, the result is `+0`.
+-   If <code>x<sub>i</sub></code> is `+infinity`, the result is `+infinity`.
 
 #### Parameters
 
@@ -103,9 +103,9 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic c
 
 ### <a name="add" href="#add">#</a> add(x1, x2, /, *, out=None)
 
-Calculates the sum for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`.
+Calculates the sum for each element <code>x1<sub>i</sub></code> of the input array `x1` with the respective element <code>x2<sub>i</sub></code> of the input array `x2`.
 
--   If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`.
+-   If either <code>x1<sub>i</sub></code> or <code>x2<sub>i</sub></code> is `NaN`, the result is `NaN`.
 
 #### Parameters
 
@@ -119,13 +119,13 @@ Calculates the sum for each element `x1_i` of the input array `x1` with the resp
 
 ### <a name="asin" href="#asin">#</a> asin(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation of the principal value of the inverse sine, having domain `[-1, +1]` and codomain `[-π/2, +π/2]` for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians.
+Calculates an implementation-dependent approximation of the principal value of the inverse sine, having domain `[-1, +1]` and codomain `[-π/2, +π/2]` for each element <code>x<sub>i</sub></code> of the input array `x`. Each element-wise result is expressed in radians.
 
--   If `x_i` is `NaN`, the result is `NaN`.
--   If `x_i` is greater than `1`, the result is `NaN`.
--   If `x_i` is less than `-1`, the result is `NaN`.
--   If `x_i` is `+0`, the result is `+0`.
--   If `x_i` is `-0`, the result is `-0`.
+-   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is greater than `1`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is less than `-1`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is `+0`, the result is `+0`.
+-   If <code>x<sub>i</sub></code> is `-0`, the result is `-0`.
 
 #### Parameters
 
@@ -138,13 +138,13 @@ Calculates an implementation-dependent approximation of the principal value of t
 
 ### <a name="asinh" href="#asinh">#</a> asinh(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the inverse hyperbolic sine, having domain `[-infinity, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` in the input array `x`.
+Calculates an implementation-dependent approximation to the inverse hyperbolic sine, having domain `[-infinity, +infinity]` and codomain `[-infinity, +infinity]`, for each element <code>x<sub>i</sub></code> in the input array `x`.
 
--   If `x_i` is `NaN`, the result is `NaN`.
--   If `x_i` is `+0`, the result is `+0`.
--   If `x_i` is `-0`, the result is `-0`.
--   If `x_i` is `+infinity`, the result is `+infinity`.
--   If `x_i` is `-infinity`, the result is `-infinity`.
+-   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is `+0`, the result is `+0`.
+-   If <code>x<sub>i</sub></code> is `-0`, the result is `-0`.
+-   If <code>x<sub>i</sub></code> is `+infinity`, the result is `+infinity`.
+-   If <code>x<sub>i</sub></code> is `-infinity`, the result is `-infinity`.
 
 #### Parameters
 
@@ -157,13 +157,13 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic s
 
 ### <a name="atan" href="#atan">#</a> atan(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation of the principal value of the inverse tangent, having domain `[-infinity, +infinity]` and codomain `[-π/2, +π/2]`, for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians.
+Calculates an implementation-dependent approximation of the principal value of the inverse tangent, having domain `[-infinity, +infinity]` and codomain `[-π/2, +π/2]`, for each element <code>x<sub>i</sub></code> of the input array `x`. Each element-wise result is expressed in radians.
 
--   If `x_i` is `NaN`, the result is `NaN`.
--   If `x_i` is `+0`, the result is `+0`.
--   If `x_i` is `-0`, the result is `-0`.
--   If `x_i` is `+infinity`, the result is an implementation-dependent approximation to `+π/2` (rounded).
--   If `x_i` is `-infinity`, the result is an implementation-dependent approximation to `-π/2` (rounded).
+-   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is `+0`, the result is `+0`.
+-   If <code>x<sub>i</sub></code> is `-0`, the result is `-0`.
+-   If <code>x<sub>i</sub></code> is `+infinity`, the result is an implementation-dependent approximation to `+π/2` (rounded).
+-   If <code>x<sub>i</sub></code> is `-infinity`, the result is an implementation-dependent approximation to `-π/2` (rounded).
 
 #### Parameters
 
@@ -176,15 +176,15 @@ Calculates an implementation-dependent approximation of the principal value of t
 
 ### <a name="atanh" href="#atanh">#</a> atanh(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the inverse hyperbolic tangent, having domain `[-1, +1]` and codomain `[-infinity, +infinity]`, for each element `x_i` of the input array `x`.
+Calculates an implementation-dependent approximation to the inverse hyperbolic tangent, having domain `[-1, +1]` and codomain `[-infinity, +infinity]`, for each element <code>x<sub>i</sub></code> of the input array `x`.
 
--   If `x_i` is `NaN`, the result is `NaN`.
--   If `x_i` is less than `-1`, the result is `NaN`.
--   If `x_i` is greater than `1`, the result is `NaN`.
--   If `x_i` is `-1`, the result is `-infinity`.
--   If `x_i` is `+1`, the result is `+infinity`.
--   If `x_i` is `+0`, the result is `+0`.
--   If `x_i` is `-0`, the result is `-0`.
+-   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is less than `-1`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is greater than `1`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is `-1`, the result is `-infinity`.
+-   If <code>x<sub>i</sub></code> is `+1`, the result is `+infinity`.
+-   If <code>x<sub>i</sub></code> is `+0`, the result is `+0`.
+-   If <code>x<sub>i</sub></code> is `-0`, the result is `-0`.
 
 #### Parameters
 
@@ -197,9 +197,9 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic t
 
 ### <a name="ceil" href="#ceil">#</a> ceil(x, /, *, out=None)
 
-Rounds each element `x_i` of the input array `x` to the smallest (i.e., closest to `-infinity`) integer-valued number that is not less than `x_i`.
+Rounds each element <code>x<sub>i</sub></code> of the input array `x` to the smallest (i.e., closest to `-infinity`) integer-valued number that is not less than <code>x<sub>i</sub></code>.
 
--   If `x_i` is already integer-valued, the result is `x_i`.
+-   If <code>x<sub>i</sub></code> is already integer-valued, the result is <code>x<sub>i</sub></code>.
 
 #### Parameters
 
@@ -212,13 +212,13 @@ Rounds each element `x_i` of the input array `x` to the smallest (i.e., closest
 
 ### <a name="cos" href="#cos">#</a> cos(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the cosine, having domain `(-infinity, +infinity)` and codomain `[-1, +1]`, for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.
+Calculates an implementation-dependent approximation to the cosine, having domain `(-infinity, +infinity)` and codomain `[-1, +1]`, for each element <code>x<sub>i</sub></code> of the input array `x`. Each element <code>x<sub>i</sub></code> is assumed to be expressed in radians.
 
--   If `x_i` is `NaN`, the result is `NaN`.
--   If `x_i` is `+0`, the result is `1`.
--   If `x_i` is `-0`, the result is `1`.
--   If `x_i` is `+infinity`, the result is `NaN`.
--   If `x_i` is `-infinity`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is `+0`, the result is `1`.
+-   If <code>x<sub>i</sub></code> is `-0`, the result is `1`.
+-   If <code>x<sub>i</sub></code> is `+infinity`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is `-infinity`, the result is `NaN`.
 
 #### Parameters
 
@@ -231,13 +231,13 @@ Calculates an implementation-dependent approximation to the cosine, having domai
 
 ### <a name="cosh" href="#cosh">#</a> cosh(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the hyperbolic cosine, having domain `[-infinity, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` in the input array `x`.
+Calculates an implementation-dependent approximation to the hyperbolic cosine, having domain `[-infinity, +infinity]` and codomain `[-infinity, +infinity]`, for each element <code>x<sub>i</sub></code> in the input array `x`.
 
--   If `x_i` is `NaN`, the result is `NaN`.
--   If `x_i` is `+0`, the result is `1`.
--   If `x_i` is `-0`, the result is `1`.
--   If `x_i` is `+infinity`, the result is `+infinity`.
--   If `x_i` is `-infinity`, the result is `+infinity`.
+-   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is `+0`, the result is `1`.
+-   If <code>x<sub>i</sub></code> is `-0`, the result is `1`.
+-   If <code>x<sub>i</sub></code> is `+infinity`, the result is `+infinity`.
+-   If <code>x<sub>i</sub></code> is `-infinity`, the result is `+infinity`.
 
 #### Parameters
 
@@ -250,9 +250,9 @@ Calculates an implementation-dependent approximation to the hyperbolic cosine, h
 
 ### <a name="divide" href="#divide">#</a> divide(x1, x2, /, *, out=None)
 
-Calculates the division for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`.
+Calculates the division for each element <code>x1<sub>i</sub></code> of the input array `x1` with the respective element <code>x2<sub>i</sub></code> of the input array `x2`.
 
--   If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`.
+-   If either <code>x1<sub>i</sub></code> or <code>x2<sub>i</sub></code> is `NaN`, the result is `NaN`.
 
 #### Parameters
 
@@ -266,13 +266,13 @@ Calculates the division for each element `x1_i` of the input array `x1` with the
 
 ### <a name="exp" href="#exp">#</a> exp(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the exponential function, having domain `[-infinity, +infinity]` and codomain `[+0, +infinity]`, for each element `x_i` of the input array `x` (`e` raised to the power of `x_i`, where `e` is the base of the natural logarithm).
+Calculates an implementation-dependent approximation to the exponential function, having domain `[-infinity, +infinity]` and codomain `[+0, +infinity]`, for each element <code>x<sub>i</sub></code> of the input array `x` (`e` raised to the power of <code>x<sub>i</sub></code>, where `e` is the base of the natural logarithm).
 
--   If `x_i` is `NaN`, the result is `NaN`.
--   If `x_i` is `+0`, the result is `1`.
--   If `x_i` is `-0`, the result is `1`.
--   If `x_i` is `+infinity`, the result is `+infinity`.
--   If `x_i` is `-infinity`, the result is `+0`.
+-   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is `+0`, the result is `1`.
+-   If <code>x<sub>i</sub></code> is `-0`, the result is `1`.
+-   If <code>x<sub>i</sub></code> is `+infinity`, the result is `+infinity`.
+-   If <code>x<sub>i</sub></code> is `-infinity`, the result is `+0`.
 
 #### Parameters
 
@@ -285,9 +285,9 @@ Calculates an implementation-dependent approximation to the exponential function
 
 ### <a name="floor" href="#floor">#</a> floor(x, /, *, out=None)
 
-Rounds each element `x_i` of the input array `x` to the greatest (i.e., closest to `+infinity`) integer-valued number that is not greater than `x_i`.
+Rounds each element <code>x<sub>i</sub></code> of the input array `x` to the greatest (i.e., closest to `+infinity`) integer-valued number that is not greater than <code>x<sub>i</sub></code>.
 
--   If `x_i` is already integer-valued, the result is `x_i`.
+-   If <code>x<sub>i</sub></code> is already integer-valued, the result is <code>x<sub>i</sub></code>.
 
 #### Parameters
 
@@ -300,13 +300,13 @@ Rounds each element `x_i` of the input array `x` to the greatest (i.e., closest
 
 ### <a name="log" href="#log">#</a> log(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the natural (base `e`) logarithm, having domain `[0, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` of the input array `x`.
+Calculates an implementation-dependent approximation to the natural (base `e`) logarithm, having domain `[0, +infinity]` and codomain `[-infinity, +infinity]`, for each element <code>x<sub>i</sub></code> of the input array `x`.
 
--   If `x_i` is `NaN`, the result is `NaN`.
--   If `x_i` is less than `0`, the result is `NaN`.
--   If `x_i` is `+0` or `-0`, the result is `-infinity`.
--   If `x_i` is `1`, the result is `+0`.
--   If `x_i` is `+infinity`, the result is `+infinity`.
+-   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is less than `0`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is `+0` or `-0`, the result is `-infinity`.
+-   If <code>x<sub>i</sub></code> is `1`, the result is `+0`.
+-   If <code>x<sub>i</sub></code> is `+infinity`, the result is `+infinity`.
 
 #### Parameters
 
@@ -319,9 +319,9 @@ Calculates an implementation-dependent approximation to the natural (base `e`) l
 
 ### <a name="multiply" href="#multiply">#</a> multiply(x1, x2, /, *, out=None)
 
-Calculates the product for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`.
+Calculates the product for each element <code>x1<sub>i</sub></code> of the input array `x1` with the respective element <code>x2<sub>i</sub></code> of the input array `x2`.
 
--   If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`.
+-   If either <code>x1<sub>i</sub></code> or <code>x2<sub>i</sub></code> is `NaN`, the result is `NaN`.
 
 #### Parameters
 
@@ -335,10 +335,10 @@ Calculates the product for each element `x1_i` of the input array `x1` with the
 
 ### <a name="round" href="#round">#</a> round(x, /, *, out=None)
 
-Rounds each element `x_i` of the input array `x` to the nearest integer-valued number.
+Rounds each element <code>x<sub>i</sub></code> of the input array `x` to the nearest integer-valued number.
 
--   If `x_i` is already integer-valued, the result is `x_i`.
--   If two integers are equally close to `x_i`, the result is whichever integer is farthest from `0`.
+-   If <code>x<sub>i</sub></code> is already integer-valued, the result is <code>x<sub>i</sub></code>.
+-   If two integers are equally close to <code>x<sub>i</sub></code>, the result is whichever integer is farthest from `0`.
 
 #### Parameters
 
@@ -351,12 +351,12 @@ Rounds each element `x_i` of the input array `x` to the nearest integer-valued n
 
 ### <a name="sin" href="#sin">#</a> sin(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the sine, having domain `(-infinity, +infinity)` and codomain `[-1, +1]`, for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.
+Calculates an implementation-dependent approximation to the sine, having domain `(-infinity, +infinity)` and codomain `[-1, +1]`, for each element <code>x<sub>i</sub></code> of the input array `x`. Each element <code>x<sub>i</sub></code> is assumed to be expressed in radians.
 
--   If `x_i` is `NaN`, the result is `NaN`.
--   If `x_i` is `+0`, the result is `+0`.
--   If `x_i` is `-0`, the result is `-0`.
--   If `x_i` is `+infinity` or `-infinity`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is `+0`, the result is `+0`.
+-   If <code>x<sub>i</sub></code> is `-0`, the result is `-0`.
+-   If <code>x<sub>i</sub></code> is `+infinity` or `-infinity`, the result is `NaN`.
 
 #### Parameters
 
@@ -369,13 +369,13 @@ Calculates an implementation-dependent approximation to the sine, having domain
 
 ### <a name="sinh" href="#sinh">#</a> sinh(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the hyperbolic sine, having domain `[-infinity, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` of the input array `x`.
+Calculates an implementation-dependent approximation to the hyperbolic sine, having domain `[-infinity, +infinity]` and codomain `[-infinity, +infinity]`, for each element <code>x<sub>i</sub></code> of the input array `x`.
 
--   If `x_i` is `NaN`, the result is `NaN`.
--   If `x_i` is `+0`, the result is `+0`.
--   If `x_i` is `-0`, the result is `-0`.
--   If `x_i` is `+infinity`, the result is `+infinity`.
--   If `x_i` is `-infinity`, the result is `-infinity`.
+-   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is `+0`, the result is `+0`.
+-   If <code>x<sub>i</sub></code> is `-0`, the result is `-0`.
+-   If <code>x<sub>i</sub></code> is `+infinity`, the result is `+infinity`.
+-   If <code>x<sub>i</sub></code> is `-infinity`, the result is `-infinity`.
 
 #### Parameters
 
@@ -388,13 +388,13 @@ Calculates an implementation-dependent approximation to the hyperbolic sine, hav
 
 ### <a name="sqrt" href="#sqrt">#</a> sqrt(x, /, *, out=None)
 
-Calculates the square root, having domain `[0, +infinity]` and codomain `[0, +infinity]`, for each element `x_i` of the input array `x`. After rounding, each result should be indistinguishable from the infinitely precise result (as required by IEEE 754).
+Calculates the square root, having domain `[0, +infinity]` and codomain `[0, +infinity]`, for each element <code>x<sub>i</sub></code> of the input array `x`. After rounding, each result should be indistinguishable from the infinitely precise result (as required by IEEE 754).
 
--   If `x_i` is `NaN`, the result is `NaN`.
--   If `x_i` is less than `0`, the result is `NaN`.
--   If `x_i` is `+0`, the result is `+0`.
--   If `x_i` is `-0`, the result is `-0`.
--   If `x_i` is `+infinity`, the result is `+infinity`.
+-   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is less than `0`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is `+0`, the result is `+0`.
+-   If <code>x<sub>i</sub></code> is `-0`, the result is `-0`.
+-   If <code>x<sub>i</sub></code> is `+infinity`, the result is `+infinity`.
 
 #### Parameters
 
@@ -407,9 +407,9 @@ Calculates the square root, having domain `[0, +infinity]` and codomain `[0, +in
 
 ### <a name="subtract" href="#subtract">#</a> subtract(x1, x2, /, *, out=None)
 
-Calculates the difference for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`.
+Calculates the difference for each element <code>x1<sub>i</sub></code> of the input array `x1` with the respective element <code>x2<sub>i</sub></code> of the input array `x2`.
 
--   If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`.
+-   If either <code>x1<sub>i</sub></code> or <code>x2<sub>i</sub></code> is `NaN`, the result is `NaN`.
 
 #### Parameters
 
@@ -423,12 +423,12 @@ Calculates the difference for each element `x1_i` of the input array `x1` with t
 
 ### <a name="tan" href="#tan">#</a> tan(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the tangent, having domain `(-infinity, +infinity)` and codomain `(-infinity, +infinity)`, for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.
+Calculates an implementation-dependent approximation to the tangent, having domain `(-infinity, +infinity)` and codomain `(-infinity, +infinity)`, for each element <code>x<sub>i</sub></code> of the input array `x`. Each element <code>x<sub>i</sub></code> is assumed to be expressed in radians.
 
--   If `x_i` is `NaN`, the result is `NaN`.
--   If `x_i` is `+0`, the result is `+0`.
--   If `x_i` is `-0`, the result is `-0`.
--   If `x_i` is `+infinity` or `-infinity`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is `+0`, the result is `+0`.
+-   If <code>x<sub>i</sub></code> is `-0`, the result is `-0`.
+-   If <code>x<sub>i</sub></code> is `+infinity` or `-infinity`, the result is `NaN`.
 
 #### Parameters
 
@@ -441,13 +441,13 @@ Calculates an implementation-dependent approximation to the tangent, having doma
 
 ### <a name="tanh" href="#tanh">#</a> tanh(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the hyperbolic tangent, having domain `[-infinity, +infinity]` and codomain `[-1, +1]`, for each element `x_i` of the input array `x`.
+Calculates an implementation-dependent approximation to the hyperbolic tangent, having domain `[-infinity, +infinity]` and codomain `[-1, +1]`, for each element <code>x<sub>i</sub></code> of the input array `x`.
 
--   If `x_i` is `NaN`, the result is `NaN`.
--   If `x_i` is `+0`, the result is `+0`.
--   If `x_i` is `-0`, the result is `-0`.
--   If `x_i` is `+infinity`, the result is `+1`.
--   If `x_i` is `-infinity`, the result is `-1`.
+-   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
+-   If <code>x<sub>i</sub></code> is `+0`, the result is `+0`.
+-   If <code>x<sub>i</sub></code> is `-0`, the result is `-0`.
+-   If <code>x<sub>i</sub></code> is `+infinity`, the result is `+1`.
+-   If <code>x<sub>i</sub></code> is `-infinity`, the result is `-1`.
 
 #### Parameters
 
@@ -460,9 +460,9 @@ Calculates an implementation-dependent approximation to the hyperbolic tangent,
 
 ### <a name="trunc" href="#trunc">#</a> trunc(x, /, *, out=None)
 
-Rounds each element `x_i` of the input array `x` to the integer-valued number that is closest to but no greater than `x_i`.
+Rounds each element <code>x<sub>i</sub></code> of the input array `x` to the integer-valued number that is closest to but no greater than <code>x<sub>i</sub></code>.
 
--   If `x_i` is already integer-valued, the result is `x_i`.
+-   If <code>x<sub>i</sub></code> is already integer-valued, the result is <code>x<sub>i</sub></code>.
 
 #### Parameters
 

From 7f37fccbd80a275efa450eb471b43dbff8a2f257 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Thu, 30 Jul 2020 15:28:25 -0700
Subject: [PATCH 16/67] Update phrasing

---
 spec/API_specification/elementwise_functions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index c775a7396..9dbab4a10 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -32,7 +32,7 @@ a tuple of `N` non-negative integers that specify the sizes of each dimension an
 
 ### element-wise
 
-an operation performed element-by-element, in which individual array elements are considered in isolation and independently of surrounding array elements.
+an operation performed element-by-element, in which individual array elements are considered in isolation and independently of other elements within the same array.
 
 * * *
 

From 63ef729fbd14f600bd86fd87128327638b54df20 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Sun, 2 Aug 2020 21:59:43 -0700
Subject: [PATCH 17/67] Revert use of HTML markup for subscripts

---
 .../elementwise_functions.md                  | 202 +++++++++---------
 1 file changed, 101 insertions(+), 101 deletions(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index 9dbab4a10..d36abfe15 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -50,11 +50,11 @@ A conforming implementation of the array API standard must provide and support t
 
 ### <a name="abs" href="#abs">#</a> abs(x, /, *, out=None)
 
-Calculates the absolute value for each element <code>x<sub>i</sub></code> of the input array `x` (i.e., the element-wise result has the same magnitude as the respective element in `x` but has positive sign).
+Calculates the absolute value for each element `x_i` of the input array `x` (i.e., the element-wise result has the same magnitude as the respective element in `x` but has positive sign).
 
--   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is `-0`, the result is `+0`.
--   If <code>x<sub>i</sub></code> is `-infinity`, the result is `+infinity`.
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is `-0`, the result is `+0`.
+-   If `x_i` is `-infinity`, the result is `+infinity`.
 
 #### Parameters
 
@@ -67,12 +67,12 @@ Calculates the absolute value for each element <code>x<sub>i</sub></code> of the
 
 ### <a name="acos" href="#acos">#</a> acos(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation of the principal value of the inverse cosine, having domain `[-1, +1]` and codomain `[+0, +π]`, for each element <code>x<sub>i</sub></code> of the input array `x`. Each element-wise result is expressed in radians.
+Calculates an implementation-dependent approximation of the principal value of the inverse cosine, having domain `[-1, +1]` and codomain `[+0, +π]`, for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians.
 
--   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is greater than `1`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is less than `-1`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is exactly `1`, the result is `+0`.
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is greater than `1`, the result is `NaN`.
+-   If `x_i` is less than `-1`, the result is `NaN`.
+-   If `x_i` is exactly `1`, the result is `+0`.
 
 #### Parameters
 
@@ -85,12 +85,12 @@ Calculates an implementation-dependent approximation of the principal value of t
 
 ### <a name="acosh" href="#acosh">#</a> acosh(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the inverse hyperbolic cosine, having domain `[+1, +infinity]` and codomain `[+0, +infinity]`, for each element <code>x<sub>i</sub></code> of the input array `x`.
+Calculates an implementation-dependent approximation to the inverse hyperbolic cosine, having domain `[+1, +infinity]` and codomain `[+0, +infinity]`, for each element `x_i` of the input array `x`.
 
--   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is less than `1`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is `1`, the result is `+0`.
--   If <code>x<sub>i</sub></code> is `+infinity`, the result is `+infinity`.
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is less than `1`, the result is `NaN`.
+-   If `x_i` is `1`, the result is `+0`.
+-   If `x_i` is `+infinity`, the result is `+infinity`.
 
 #### Parameters
 
@@ -119,13 +119,13 @@ Calculates the sum for each element <code>x1<sub>i</sub></code> of the input arr
 
 ### <a name="asin" href="#asin">#</a> asin(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation of the principal value of the inverse sine, having domain `[-1, +1]` and codomain `[-π/2, +π/2]` for each element <code>x<sub>i</sub></code> of the input array `x`. Each element-wise result is expressed in radians.
+Calculates an implementation-dependent approximation of the principal value of the inverse sine, having domain `[-1, +1]` and codomain `[-π/2, +π/2]` for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians.
 
--   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is greater than `1`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is less than `-1`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is `+0`, the result is `+0`.
--   If <code>x<sub>i</sub></code> is `-0`, the result is `-0`.
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is greater than `1`, the result is `NaN`.
+-   If `x_i` is less than `-1`, the result is `NaN`.
+-   If `x_i` is `+0`, the result is `+0`.
+-   If `x_i` is `-0`, the result is `-0`.
 
 #### Parameters
 
@@ -138,13 +138,13 @@ Calculates an implementation-dependent approximation of the principal value of t
 
 ### <a name="asinh" href="#asinh">#</a> asinh(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the inverse hyperbolic sine, having domain `[-infinity, +infinity]` and codomain `[-infinity, +infinity]`, for each element <code>x<sub>i</sub></code> in the input array `x`.
+Calculates an implementation-dependent approximation to the inverse hyperbolic sine, having domain `[-infinity, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` in the input array `x`.
 
--   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is `+0`, the result is `+0`.
--   If <code>x<sub>i</sub></code> is `-0`, the result is `-0`.
--   If <code>x<sub>i</sub></code> is `+infinity`, the result is `+infinity`.
--   If <code>x<sub>i</sub></code> is `-infinity`, the result is `-infinity`.
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is `+0`, the result is `+0`.
+-   If `x_i` is `-0`, the result is `-0`.
+-   If `x_i` is `+infinity`, the result is `+infinity`.
+-   If `x_i` is `-infinity`, the result is `-infinity`.
 
 #### Parameters
 
@@ -157,13 +157,13 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic s
 
 ### <a name="atan" href="#atan">#</a> atan(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation of the principal value of the inverse tangent, having domain `[-infinity, +infinity]` and codomain `[-π/2, +π/2]`, for each element <code>x<sub>i</sub></code> of the input array `x`. Each element-wise result is expressed in radians.
+Calculates an implementation-dependent approximation of the principal value of the inverse tangent, having domain `[-infinity, +infinity]` and codomain `[-π/2, +π/2]`, for each element `x_i` of the input array `x`. Each element-wise result is expressed in radians.
 
--   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is `+0`, the result is `+0`.
--   If <code>x<sub>i</sub></code> is `-0`, the result is `-0`.
--   If <code>x<sub>i</sub></code> is `+infinity`, the result is an implementation-dependent approximation to `+π/2` (rounded).
--   If <code>x<sub>i</sub></code> is `-infinity`, the result is an implementation-dependent approximation to `-π/2` (rounded).
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is `+0`, the result is `+0`.
+-   If `x_i` is `-0`, the result is `-0`.
+-   If `x_i` is `+infinity`, the result is an implementation-dependent approximation to `+π/2` (rounded).
+-   If `x_i` is `-infinity`, the result is an implementation-dependent approximation to `-π/2` (rounded).
 
 #### Parameters
 
@@ -176,15 +176,15 @@ Calculates an implementation-dependent approximation of the principal value of t
 
 ### <a name="atanh" href="#atanh">#</a> atanh(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the inverse hyperbolic tangent, having domain `[-1, +1]` and codomain `[-infinity, +infinity]`, for each element <code>x<sub>i</sub></code> of the input array `x`.
+Calculates an implementation-dependent approximation to the inverse hyperbolic tangent, having domain `[-1, +1]` and codomain `[-infinity, +infinity]`, for each element `x_i` of the input array `x`.
 
--   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is less than `-1`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is greater than `1`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is `-1`, the result is `-infinity`.
--   If <code>x<sub>i</sub></code> is `+1`, the result is `+infinity`.
--   If <code>x<sub>i</sub></code> is `+0`, the result is `+0`.
--   If <code>x<sub>i</sub></code> is `-0`, the result is `-0`.
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is less than `-1`, the result is `NaN`.
+-   If `x_i` is greater than `1`, the result is `NaN`.
+-   If `x_i` is `-1`, the result is `-infinity`.
+-   If `x_i` is `+1`, the result is `+infinity`.
+-   If `x_i` is `+0`, the result is `+0`.
+-   If `x_i` is `-0`, the result is `-0`.
 
 #### Parameters
 
@@ -197,9 +197,9 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic t
 
 ### <a name="ceil" href="#ceil">#</a> ceil(x, /, *, out=None)
 
-Rounds each element <code>x<sub>i</sub></code> of the input array `x` to the smallest (i.e., closest to `-infinity`) integer-valued number that is not less than <code>x<sub>i</sub></code>.
+Rounds each element `x_i` of the input array `x` to the smallest (i.e., closest to `-infinity`) integer-valued number that is not less than `x_i`.
 
--   If <code>x<sub>i</sub></code> is already integer-valued, the result is <code>x<sub>i</sub></code>.
+-   If `x_i` is already integer-valued, the result is `x_i`.
 
 #### Parameters
 
@@ -212,13 +212,13 @@ Rounds each element <code>x<sub>i</sub></code> of the input array `x` to the sma
 
 ### <a name="cos" href="#cos">#</a> cos(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the cosine, having domain `(-infinity, +infinity)` and codomain `[-1, +1]`, for each element <code>x<sub>i</sub></code> of the input array `x`. Each element <code>x<sub>i</sub></code> is assumed to be expressed in radians.
+Calculates an implementation-dependent approximation to the cosine, having domain `(-infinity, +infinity)` and codomain `[-1, +1]`, for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.
 
--   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is `+0`, the result is `1`.
--   If <code>x<sub>i</sub></code> is `-0`, the result is `1`.
--   If <code>x<sub>i</sub></code> is `+infinity`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is `-infinity`, the result is `NaN`.
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is `+0`, the result is `1`.
+-   If `x_i` is `-0`, the result is `1`.
+-   If `x_i` is `+infinity`, the result is `NaN`.
+-   If `x_i` is `-infinity`, the result is `NaN`.
 
 #### Parameters
 
@@ -231,13 +231,13 @@ Calculates an implementation-dependent approximation to the cosine, having domai
 
 ### <a name="cosh" href="#cosh">#</a> cosh(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the hyperbolic cosine, having domain `[-infinity, +infinity]` and codomain `[-infinity, +infinity]`, for each element <code>x<sub>i</sub></code> in the input array `x`.
+Calculates an implementation-dependent approximation to the hyperbolic cosine, having domain `[-infinity, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` in the input array `x`.
 
--   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is `+0`, the result is `1`.
--   If <code>x<sub>i</sub></code> is `-0`, the result is `1`.
--   If <code>x<sub>i</sub></code> is `+infinity`, the result is `+infinity`.
--   If <code>x<sub>i</sub></code> is `-infinity`, the result is `+infinity`.
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is `+0`, the result is `1`.
+-   If `x_i` is `-0`, the result is `1`.
+-   If `x_i` is `+infinity`, the result is `+infinity`.
+-   If `x_i` is `-infinity`, the result is `+infinity`.
 
 #### Parameters
 
@@ -266,13 +266,13 @@ Calculates the division for each element <code>x1<sub>i</sub></code> of the inpu
 
 ### <a name="exp" href="#exp">#</a> exp(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the exponential function, having domain `[-infinity, +infinity]` and codomain `[+0, +infinity]`, for each element <code>x<sub>i</sub></code> of the input array `x` (`e` raised to the power of <code>x<sub>i</sub></code>, where `e` is the base of the natural logarithm).
+Calculates an implementation-dependent approximation to the exponential function, having domain `[-infinity, +infinity]` and codomain `[+0, +infinity]`, for each element `x_i` of the input array `x` (`e` raised to the power of `x_i`, where `e` is the base of the natural logarithm).
 
--   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is `+0`, the result is `1`.
--   If <code>x<sub>i</sub></code> is `-0`, the result is `1`.
--   If <code>x<sub>i</sub></code> is `+infinity`, the result is `+infinity`.
--   If <code>x<sub>i</sub></code> is `-infinity`, the result is `+0`.
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is `+0`, the result is `1`.
+-   If `x_i` is `-0`, the result is `1`.
+-   If `x_i` is `+infinity`, the result is `+infinity`.
+-   If `x_i` is `-infinity`, the result is `+0`.
 
 #### Parameters
 
@@ -285,9 +285,9 @@ Calculates an implementation-dependent approximation to the exponential function
 
 ### <a name="floor" href="#floor">#</a> floor(x, /, *, out=None)
 
-Rounds each element <code>x<sub>i</sub></code> of the input array `x` to the greatest (i.e., closest to `+infinity`) integer-valued number that is not greater than <code>x<sub>i</sub></code>.
+Rounds each element `x_i` of the input array `x` to the greatest (i.e., closest to `+infinity`) integer-valued number that is not greater than `x_i`.
 
--   If <code>x<sub>i</sub></code> is already integer-valued, the result is <code>x<sub>i</sub></code>.
+-   If `x_i` is already integer-valued, the result is `x_i`.
 
 #### Parameters
 
@@ -300,13 +300,13 @@ Rounds each element <code>x<sub>i</sub></code> of the input array `x` to the gre
 
 ### <a name="log" href="#log">#</a> log(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the natural (base `e`) logarithm, having domain `[0, +infinity]` and codomain `[-infinity, +infinity]`, for each element <code>x<sub>i</sub></code> of the input array `x`.
+Calculates an implementation-dependent approximation to the natural (base `e`) logarithm, having domain `[0, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` of the input array `x`.
 
--   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is less than `0`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is `+0` or `-0`, the result is `-infinity`.
--   If <code>x<sub>i</sub></code> is `1`, the result is `+0`.
--   If <code>x<sub>i</sub></code> is `+infinity`, the result is `+infinity`.
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is less than `0`, the result is `NaN`.
+-   If `x_i` is `+0` or `-0`, the result is `-infinity`.
+-   If `x_i` is `1`, the result is `+0`.
+-   If `x_i` is `+infinity`, the result is `+infinity`.
 
 #### Parameters
 
@@ -335,10 +335,10 @@ Calculates the product for each element <code>x1<sub>i</sub></code> of the input
 
 ### <a name="round" href="#round">#</a> round(x, /, *, out=None)
 
-Rounds each element <code>x<sub>i</sub></code> of the input array `x` to the nearest integer-valued number.
+Rounds each element `x_i` of the input array `x` to the nearest integer-valued number.
 
--   If <code>x<sub>i</sub></code> is already integer-valued, the result is <code>x<sub>i</sub></code>.
--   If two integers are equally close to <code>x<sub>i</sub></code>, the result is whichever integer is farthest from `0`.
+-   If `x_i` is already integer-valued, the result is `x_i`.
+-   If two integers are equally close to `x_i`, the result is whichever integer is farthest from `0`.
 
 #### Parameters
 
@@ -351,12 +351,12 @@ Rounds each element <code>x<sub>i</sub></code> of the input array `x` to the nea
 
 ### <a name="sin" href="#sin">#</a> sin(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the sine, having domain `(-infinity, +infinity)` and codomain `[-1, +1]`, for each element <code>x<sub>i</sub></code> of the input array `x`. Each element <code>x<sub>i</sub></code> is assumed to be expressed in radians.
+Calculates an implementation-dependent approximation to the sine, having domain `(-infinity, +infinity)` and codomain `[-1, +1]`, for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.
 
--   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is `+0`, the result is `+0`.
--   If <code>x<sub>i</sub></code> is `-0`, the result is `-0`.
--   If <code>x<sub>i</sub></code> is `+infinity` or `-infinity`, the result is `NaN`.
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is `+0`, the result is `+0`.
+-   If `x_i` is `-0`, the result is `-0`.
+-   If `x_i` is `+infinity` or `-infinity`, the result is `NaN`.
 
 #### Parameters
 
@@ -369,13 +369,13 @@ Calculates an implementation-dependent approximation to the sine, having domain
 
 ### <a name="sinh" href="#sinh">#</a> sinh(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the hyperbolic sine, having domain `[-infinity, +infinity]` and codomain `[-infinity, +infinity]`, for each element <code>x<sub>i</sub></code> of the input array `x`.
+Calculates an implementation-dependent approximation to the hyperbolic sine, having domain `[-infinity, +infinity]` and codomain `[-infinity, +infinity]`, for each element `x_i` of the input array `x`.
 
--   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is `+0`, the result is `+0`.
--   If <code>x<sub>i</sub></code> is `-0`, the result is `-0`.
--   If <code>x<sub>i</sub></code> is `+infinity`, the result is `+infinity`.
--   If <code>x<sub>i</sub></code> is `-infinity`, the result is `-infinity`.
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is `+0`, the result is `+0`.
+-   If `x_i` is `-0`, the result is `-0`.
+-   If `x_i` is `+infinity`, the result is `+infinity`.
+-   If `x_i` is `-infinity`, the result is `-infinity`.
 
 #### Parameters
 
@@ -388,13 +388,13 @@ Calculates an implementation-dependent approximation to the hyperbolic sine, hav
 
 ### <a name="sqrt" href="#sqrt">#</a> sqrt(x, /, *, out=None)
 
-Calculates the square root, having domain `[0, +infinity]` and codomain `[0, +infinity]`, for each element <code>x<sub>i</sub></code> of the input array `x`. After rounding, each result should be indistinguishable from the infinitely precise result (as required by IEEE 754).
+Calculates the square root, having domain `[0, +infinity]` and codomain `[0, +infinity]`, for each element `x_i` of the input array `x`. After rounding, each result should be indistinguishable from the infinitely precise result (as required by IEEE 754).
 
--   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is less than `0`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is `+0`, the result is `+0`.
--   If <code>x<sub>i</sub></code> is `-0`, the result is `-0`.
--   If <code>x<sub>i</sub></code> is `+infinity`, the result is `+infinity`.
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is less than `0`, the result is `NaN`.
+-   If `x_i` is `+0`, the result is `+0`.
+-   If `x_i` is `-0`, the result is `-0`.
+-   If `x_i` is `+infinity`, the result is `+infinity`.
 
 #### Parameters
 
@@ -423,12 +423,12 @@ Calculates the difference for each element <code>x1<sub>i</sub></code> of the in
 
 ### <a name="tan" href="#tan">#</a> tan(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the tangent, having domain `(-infinity, +infinity)` and codomain `(-infinity, +infinity)`, for each element <code>x<sub>i</sub></code> of the input array `x`. Each element <code>x<sub>i</sub></code> is assumed to be expressed in radians.
+Calculates an implementation-dependent approximation to the tangent, having domain `(-infinity, +infinity)` and codomain `(-infinity, +infinity)`, for each element `x_i` of the input array `x`. Each element `x_i` is assumed to be expressed in radians.
 
--   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is `+0`, the result is `+0`.
--   If <code>x<sub>i</sub></code> is `-0`, the result is `-0`.
--   If <code>x<sub>i</sub></code> is `+infinity` or `-infinity`, the result is `NaN`.
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is `+0`, the result is `+0`.
+-   If `x_i` is `-0`, the result is `-0`.
+-   If `x_i` is `+infinity` or `-infinity`, the result is `NaN`.
 
 #### Parameters
 
@@ -441,13 +441,13 @@ Calculates an implementation-dependent approximation to the tangent, having doma
 
 ### <a name="tanh" href="#tanh">#</a> tanh(x, /, *, out=None)
 
-Calculates an implementation-dependent approximation to the hyperbolic tangent, having domain `[-infinity, +infinity]` and codomain `[-1, +1]`, for each element <code>x<sub>i</sub></code> of the input array `x`.
+Calculates an implementation-dependent approximation to the hyperbolic tangent, having domain `[-infinity, +infinity]` and codomain `[-1, +1]`, for each element `x_i` of the input array `x`.
 
--   If <code>x<sub>i</sub></code> is `NaN`, the result is `NaN`.
--   If <code>x<sub>i</sub></code> is `+0`, the result is `+0`.
--   If <code>x<sub>i</sub></code> is `-0`, the result is `-0`.
--   If <code>x<sub>i</sub></code> is `+infinity`, the result is `+1`.
--   If <code>x<sub>i</sub></code> is `-infinity`, the result is `-1`.
+-   If `x_i` is `NaN`, the result is `NaN`.
+-   If `x_i` is `+0`, the result is `+0`.
+-   If `x_i` is `-0`, the result is `-0`.
+-   If `x_i` is `+infinity`, the result is `+1`.
+-   If `x_i` is `-infinity`, the result is `-1`.
 
 #### Parameters
 
@@ -460,9 +460,9 @@ Calculates an implementation-dependent approximation to the hyperbolic tangent,
 
 ### <a name="trunc" href="#trunc">#</a> trunc(x, /, *, out=None)
 
-Rounds each element <code>x<sub>i</sub></code> of the input array `x` to the integer-valued number that is closest to but no greater than <code>x<sub>i</sub></code>.
+Rounds each element `x_i` of the input array `x` to the integer-valued number that is closest to but no greater than `x_i`.
 
--   If <code>x<sub>i</sub></code> is already integer-valued, the result is <code>x<sub>i</sub></code>.
+-   If `x_i` is already integer-valued, the result is `x_i`.
 
 #### Parameters
 

From 991eca683084cec6f49927706e2e774fa690b009 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Mon, 3 Aug 2020 16:04:16 -0700
Subject: [PATCH 18/67] Move terms, references, and conformance to purpose and
 scope document

---
 .../elementwise_functions.md                  | 34 -------------------
 spec/purpose_and_scope.md                     | 30 ++++++++++++++--
 2 files changed, 28 insertions(+), 36 deletions(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index d36abfe15..7229e0347 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -2,40 +2,6 @@
 
 > Array API specification for element-wise functions.
 
-## Conformance
-
-A conforming implementation of the array API standard must provide and support all the functions, arguments, syntax, and semantics described in this specification.
-
-A conforming implementation of the array API standard may provide additional values, objects, properties, and functions beyond those described in this specification.
-
-* * *
-
-## Normative References
-
-The following referenced documents are indispensable for the application of this specification.
-
--   __IEEE 754-2019: IEEE Standard for Floating-Point Arithmetic.__ Institute of Electrical and Electronic Engineers, New York (2019).
-
-* * *
-
-## Terms and Definitions
-
-For the purposes of this specification, the following terms and definitions apply.
-
-### array
-
-a (usually fixed-size) multidimensional container of items of the same type and size.
-
-### shape
-
-a tuple of `N` non-negative integers that specify the sizes of each dimension and where `N` corresponds to the number of dimensions.
-
-### element-wise
-
-an operation performed element-by-element, in which individual array elements are considered in isolation and independently of other elements within the same array.
-
-* * *
-
 ## Functions
 
 A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions.
diff --git a/spec/purpose_and_scope.md b/spec/purpose_and_scope.md
index d7b419504..ca1568a6b 100644
--- a/spec/purpose_and_scope.md
+++ b/spec/purpose_and_scope.md
@@ -30,12 +30,38 @@
 ## How to adopt this API
 
 
+* * *
 
+## Conformance
 
-## Definitions
+A conforming implementation of the array API standard must provide and support all the functions, arguments, syntax, and semantics described in this specification.
 
+A conforming implementation of the array API standard may provide additional values, objects, properties, and functions beyond those described in this specification.
 
+* * *
 
+## Terms and Definitions
 
-## References
+For the purposes of this specification, the following terms and definitions apply.
 
+<!-- NOTE: please keep the terms in alphabetical order -->
+
+### array
+
+a (usually fixed-size) multidimensional container of items of the same type and size.
+
+### element-wise
+
+an operation performed element-by-element, in which individual array elements are considered in isolation and independently of other elements within the same array.
+
+### shape
+
+a tuple of `N` non-negative integers that specify the sizes of each dimension and where `N` corresponds to the number of dimensions.
+
+* * *
+
+## Normative References
+
+The following referenced documents are indispensable for the application of this specification.
+
+-   __IEEE 754-2019: IEEE Standard for Floating-Point Arithmetic.__ Institute of Electrical and Electronic Engineers, New York (2019).
\ No newline at end of file

From f1fb7a51ae11a11f5ac0c1dc4beeb54c1389f800 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Mon, 3 Aug 2020 16:05:19 -0700
Subject: [PATCH 19/67] Remove heading

---
 spec/API_specification/elementwise_functions.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index 7229e0347..6b1c3056e 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -2,8 +2,6 @@
 
 > Array API specification for element-wise functions.
 
-## Functions
-
 A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions.
 
 -   Positional parameters must be [positional-only](https://www.python.org/dev/peps/pep-0570/) parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order.

From f009e5049ada13315e271a452b6b82274751c8c1 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Mon, 3 Aug 2020 16:16:41 -0700
Subject: [PATCH 20/67] Add definition for broadcasting

---
 spec/purpose_and_scope.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/spec/purpose_and_scope.md b/spec/purpose_and_scope.md
index ca1568a6b..510f8f632 100644
--- a/spec/purpose_and_scope.md
+++ b/spec/purpose_and_scope.md
@@ -50,6 +50,10 @@ For the purposes of this specification, the following terms and definitions appl
 
 a (usually fixed-size) multidimensional container of items of the same type and size.
 
+### broadcasting
+
+automatic (implicit) expansion of array dimensions to be of equal sizes without copying array data.
+
 ### element-wise
 
 an operation performed element-by-element, in which individual array elements are considered in isolation and independently of other elements within the same array.

From 15422fed4a62f2aa49c18d25e7afdced4fdc03c0 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Mon, 3 Aug 2020 16:32:07 -0700
Subject: [PATCH 21/67] Define compatible

---
 spec/purpose_and_scope.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/spec/purpose_and_scope.md b/spec/purpose_and_scope.md
index 510f8f632..9131c1068 100644
--- a/spec/purpose_and_scope.md
+++ b/spec/purpose_and_scope.md
@@ -50,10 +50,14 @@ For the purposes of this specification, the following terms and definitions appl
 
 a (usually fixed-size) multidimensional container of items of the same type and size.
 
-### broadcasting
+### broadcast
 
 automatic (implicit) expansion of array dimensions to be of equal sizes without copying array data.
 
+### compatible
+
+two arrays whose dimensions are compatible (i.e., where the size of each dimension in one array is either equal to one or to the size of the corresponding dimension in a second array).
+
 ### element-wise
 
 an operation performed element-by-element, in which individual array elements are considered in isolation and independently of other elements within the same array.

From 2f653eca636a1a7d644fafa3d4d9440475943fd7 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Mon, 3 Aug 2020 17:27:09 -0700
Subject: [PATCH 22/67] Add broadcasting document

---
 spec/API_specification/broadcasting.md | 99 ++++++++++++++++++++++++++
 spec/API_specification/index.rst       |  1 +
 2 files changed, 100 insertions(+)
 create mode 100644 spec/API_specification/broadcasting.md

diff --git a/spec/API_specification/broadcasting.md b/spec/API_specification/broadcasting.md
new file mode 100644
index 000000000..ad128adca
--- /dev/null
+++ b/spec/API_specification/broadcasting.md
@@ -0,0 +1,99 @@
+# Broadcasting
+
+> Array API specification for broadcasting semantics.
+
+## Overview
+
+**Broadcasting** refers to the automatic (implicit) expansion of array dimensions to be of equal sizes without copying array data.
+
+## Algorithm
+
+Given an element-wise arithmetic operation involving two compatible arrays, an array having a singleton dimension (i.e., a dimension whose size is one) is broadcast (i.e., virtually repeated) across an array having a corresponding non-singleton dimension.
+
+The results of the element-wise arithmetic operation must be stored in an array having a shape determined by the following algorithm.
+
+1.  Let `x1` and `x2` both be arrays.
+
+1.  Let `shape1` be a tuple describing the shape of array `x1`.
+
+1.  Let `shape2` be a tuple describing the shape of array `x2`.
+
+1.  Let `N1` be the number of dimensions of array `x1` (i.e., the result of `len(shape1)`).
+
+1.  Let `N2` be the number of dimensions of array `x2` (i.e., the result of `len(shape2)`).
+
+1.  Let `N` be the maximum value of `N1` and `N2` (i.e., the result of `max(N1, N2)`).
+
+1.  Let `shape` be a temporary list of length `N` for storing the shape of the result array.
+
+1.  Let `i` be `N-1`.
+
+1.  Repeat, while `i >= 0`
+
+	a.  If `N1 > i`, let `d1` be the size of dimension `n` for array `x1` (i.e., the result of `shape1[i]`); else, let `d1` be `1`.
+
+	a.  If `N2 > i`, let `d2` be the size of dimension `n` for array `x2` (i.e., the result of `shape2[i]`); else, let `d2` be `1`.
+
+	a.  If `d1 == 1`, then
+		
+		-   set `shape[i]` to `d2`.
+
+	a.  Else, if `d2 == 1`, then
+
+		-   set `shape[i]` to `d1`.
+
+	a.  Else, if `d1 == d2`, then
+
+		-   set `shape[i]` to `d1`.
+
+	a.  Else, throw an exception.
+
+	a.  Set `i` to `i-1`.
+
+1.  Let `tuple(shape)` be the shape of the result array.
+
+### Examples
+
+The following examples demonstrate the application of the broadcasting algorithm for two compatible arrays.
+
+```text
+A      (4d array):  8 x 1 x 6 x 1
+B      (3d array):      7 x 1 x 5
+---------------------------------
+Result (4d array):  8 x 7 x 6 x 5
+
+A      (2d array):  5 x 4
+B      (1d array):      1
+-------------------------
+Result (2d array):  5 x 4
+
+A      (2d array):  5 x 4
+B      (1d array):      4
+-------------------------
+Result (2d array):  5 x 4
+
+A      (3d array):  15 x 3 x 5
+B      (3d array):  15 x 1 x 5
+------------------------------
+Result (3d array):  15 x 3 x 5
+
+A      (3d array):  15 x 3 x 5
+B      (2d array):       3 x 5
+------------------------------
+Result (3d array):  15 x 3 x 5
+
+A      (3d array):  15 x 3 x 5
+B      (2d array):       3 x 1
+------------------------------
+Result (3d array):  15 x 3 x 5
+```
+
+The following examples demonstrate array shapes which do **not** broadcast.
+
+```text
+A      (1d array):  3
+B      (1d array):  4 # dimension does not match
+
+A      (2d array):      2 x 1
+B      (3d array):  8 x 4 x 3 # second dimension does not match
+```
\ No newline at end of file
diff --git a/spec/API_specification/index.rst b/spec/API_specification/index.rst
index 7035c369b..23306276e 100644
--- a/spec/API_specification/index.rst
+++ b/spec/API_specification/index.rst
@@ -8,4 +8,5 @@ API specification
    array_object
    elementwise_functions
    indexing
+   broadcasting
    casting

From 9caaff9b6a310e2c8061ffc127439265790a7aa0 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Mon, 3 Aug 2020 17:29:17 -0700
Subject: [PATCH 23/67] Fix markup

---
 spec/API_specification/broadcasting.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/spec/API_specification/broadcasting.md b/spec/API_specification/broadcasting.md
index ad128adca..b14a9699a 100644
--- a/spec/API_specification/broadcasting.md
+++ b/spec/API_specification/broadcasting.md
@@ -30,25 +30,25 @@ The results of the element-wise arithmetic operation must be stored in an array
 
 1.  Repeat, while `i >= 0`
 
-	a.  If `N1 > i`, let `d1` be the size of dimension `n` for array `x1` (i.e., the result of `shape1[i]`); else, let `d1` be `1`.
+	1.  If `N1 > i`, let `d1` be the size of dimension `n` for array `x1` (i.e., the result of `shape1[i]`); else, let `d1` be `1`.
 
-	a.  If `N2 > i`, let `d2` be the size of dimension `n` for array `x2` (i.e., the result of `shape2[i]`); else, let `d2` be `1`.
+	1.  If `N2 > i`, let `d2` be the size of dimension `n` for array `x2` (i.e., the result of `shape2[i]`); else, let `d2` be `1`.
 
-	a.  If `d1 == 1`, then
+	1.  If `d1 == 1`, then
 		
 		-   set `shape[i]` to `d2`.
 
-	a.  Else, if `d2 == 1`, then
+	1.  Else, if `d2 == 1`, then
 
 		-   set `shape[i]` to `d1`.
 
-	a.  Else, if `d1 == d2`, then
+	1.  Else, if `d1 == d2`, then
 
 		-   set `shape[i]` to `d1`.
 
-	a.  Else, throw an exception.
+	1.  Else, throw an exception.
 
-	a.  Set `i` to `i-1`.
+	1.  Set `i` to `i-1`.
 
 1.  Let `tuple(shape)` be the shape of the result array.
 

From f200206cf0ae94aa51de6b06c9de91f0b5ba0a5a Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Mon, 3 Aug 2020 17:30:25 -0700
Subject: [PATCH 24/67] Update phrasing

---
 spec/API_specification/broadcasting.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/spec/API_specification/broadcasting.md b/spec/API_specification/broadcasting.md
index b14a9699a..c9efc144a 100644
--- a/spec/API_specification/broadcasting.md
+++ b/spec/API_specification/broadcasting.md
@@ -36,15 +36,15 @@ The results of the element-wise arithmetic operation must be stored in an array
 
 	1.  If `d1 == 1`, then
 		
-		-   set `shape[i]` to `d2`.
+		-   set the `i`th element of `shape` to `d2`.
 
 	1.  Else, if `d2 == 1`, then
 
-		-   set `shape[i]` to `d1`.
+		-   set the `i`th element of `shape` to `d1`.
 
 	1.  Else, if `d1 == d2`, then
 
-		-   set `shape[i]` to `d1`.
+		-   set the `i`th element of `shape` to `d1`.
 
 	1.  Else, throw an exception.
 

From 02de24e1947e2809bf608a7349583f1ddaccd4ca Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Tue, 4 Aug 2020 11:23:45 -0700
Subject: [PATCH 25/67] Fix algorithm

---
 spec/API_specification/broadcasting.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/spec/API_specification/broadcasting.md b/spec/API_specification/broadcasting.md
index c9efc144a..870aaac25 100644
--- a/spec/API_specification/broadcasting.md
+++ b/spec/API_specification/broadcasting.md
@@ -30,9 +30,9 @@ The results of the element-wise arithmetic operation must be stored in an array
 
 1.  Repeat, while `i >= 0`
 
-	1.  If `N1 > i`, let `d1` be the size of dimension `n` for array `x1` (i.e., the result of `shape1[i]`); else, let `d1` be `1`.
+	1.  If `N1-N+i >= 0`, let `d1` be the size of dimension `n` for array `x1` (i.e., the result of `shape1[i]`); else, let `d1` be `1`.
 
-	1.  If `N2 > i`, let `d2` be the size of dimension `n` for array `x2` (i.e., the result of `shape2[i]`); else, let `d2` be `1`.
+	1.  If `N2-N+i >= 0`, let `d2` be the size of dimension `n` for array `x2` (i.e., the result of `shape2[i]`); else, let `d2` be `1`.
 
 	1.  If `d1 == 1`, then
 		

From 347973a396085b36d857d680a42f089432f18ddd Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Tue, 4 Aug 2020 11:42:52 -0700
Subject: [PATCH 26/67] Update definition

---
 spec/API_specification/broadcasting.md | 4 ++--
 spec/purpose_and_scope.md              | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/spec/API_specification/broadcasting.md b/spec/API_specification/broadcasting.md
index 870aaac25..e99091fb1 100644
--- a/spec/API_specification/broadcasting.md
+++ b/spec/API_specification/broadcasting.md
@@ -8,9 +8,9 @@
 
 ## Algorithm
 
-Given an element-wise arithmetic operation involving two compatible arrays, an array having a singleton dimension (i.e., a dimension whose size is one) is broadcast (i.e., virtually repeated) across an array having a corresponding non-singleton dimension.
+Given an element-wise operation involving two compatible arrays, an array having a singleton dimension (i.e., a dimension whose size is one) is broadcast (i.e., virtually repeated) across an array having a corresponding non-singleton dimension.
 
-The results of the element-wise arithmetic operation must be stored in an array having a shape determined by the following algorithm.
+The results of the element-wise operation must be stored in an array having a shape determined by the following algorithm.
 
 1.  Let `x1` and `x2` both be arrays.
 
diff --git a/spec/purpose_and_scope.md b/spec/purpose_and_scope.md
index 9131c1068..fcfab69db 100644
--- a/spec/purpose_and_scope.md
+++ b/spec/purpose_and_scope.md
@@ -52,7 +52,7 @@ a (usually fixed-size) multidimensional container of items of the same type and
 
 ### broadcast
 
-automatic (implicit) expansion of array dimensions to be of equal sizes without copying array data.
+automatic (implicit) expansion of array dimensions to be of equal sizes without copying array data for the purpose of making arrays with different shapes have compatible shapes for element-wise operations.
 
 ### compatible
 

From b813d9b7db2ecf3b350cff7aa930ab4bd30e1d73 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Tue, 4 Aug 2020 12:09:52 -0700
Subject: [PATCH 27/67] Expand overview and add note regarding in-place
 semantics

---
 spec/API_specification/broadcasting.md | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/spec/API_specification/broadcasting.md b/spec/API_specification/broadcasting.md
index e99091fb1..83eebb495 100644
--- a/spec/API_specification/broadcasting.md
+++ b/spec/API_specification/broadcasting.md
@@ -4,7 +4,9 @@
 
 ## Overview
 
-**Broadcasting** refers to the automatic (implicit) expansion of array dimensions to be of equal sizes without copying array data.
+**Broadcasting** refers to the automatic (implicit) expansion of array dimensions to be of equal sizes without copying array data for the purpose of making arrays with different shapes have compatible shapes for element-wise operations.
+
+Broadcasting facilitates user ergonomics by encouraging users to elide unnecessary copying of array data and can **potentially** enable more memory-efficient element-wise operations through vectorization, reduced memory consumption, and cache locality.
 
 ## Algorithm
 
@@ -96,4 +98,8 @@ B      (1d array):  4 # dimension does not match
 
 A      (2d array):      2 x 1
 B      (3d array):  8 x 4 x 3 # second dimension does not match
-```
\ No newline at end of file
+```
+
+## In-place Semantics
+
+In-place element-wise operations must not change the shape of the in-place array as a result of broadcasting.
\ No newline at end of file

From 33cd2b74df03d8f6e394e3e367f9491bb239a420 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Tue, 4 Aug 2020 12:16:22 -0700
Subject: [PATCH 28/67] Rename arrays

---
 spec/API_specification/broadcasting.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/spec/API_specification/broadcasting.md b/spec/API_specification/broadcasting.md
index 83eebb495..42f897aed 100644
--- a/spec/API_specification/broadcasting.md
+++ b/spec/API_specification/broadcasting.md
@@ -14,15 +14,15 @@ Given an element-wise operation involving two compatible arrays, an array having
 
 The results of the element-wise operation must be stored in an array having a shape determined by the following algorithm.
 
-1.  Let `x1` and `x2` both be arrays.
+1.  Let `A` and `B` both be arrays.
 
-1.  Let `shape1` be a tuple describing the shape of array `x1`.
+1.  Let `shape1` be a tuple describing the shape of array `A`.
 
-1.  Let `shape2` be a tuple describing the shape of array `x2`.
+1.  Let `shape2` be a tuple describing the shape of array `B`.
 
-1.  Let `N1` be the number of dimensions of array `x1` (i.e., the result of `len(shape1)`).
+1.  Let `N1` be the number of dimensions of array `A` (i.e., the result of `len(shape1)`).
 
-1.  Let `N2` be the number of dimensions of array `x2` (i.e., the result of `len(shape2)`).
+1.  Let `N2` be the number of dimensions of array `B` (i.e., the result of `len(shape2)`).
 
 1.  Let `N` be the maximum value of `N1` and `N2` (i.e., the result of `max(N1, N2)`).
 
@@ -32,9 +32,9 @@ The results of the element-wise operation must be stored in an array having a sh
 
 1.  Repeat, while `i >= 0`
 
-	1.  If `N1-N+i >= 0`, let `d1` be the size of dimension `n` for array `x1` (i.e., the result of `shape1[i]`); else, let `d1` be `1`.
+	1.  If `N1-N+i >= 0`, let `d1` be the size of dimension `n` for array `A` (i.e., the result of `shape1[i]`); else, let `d1` be `1`.
 
-	1.  If `N2-N+i >= 0`, let `d2` be the size of dimension `n` for array `x2` (i.e., the result of `shape2[i]`); else, let `d2` be `1`.
+	1.  If `N2-N+i >= 0`, let `d2` be the size of dimension `n` for array `B` (i.e., the result of `shape2[i]`); else, let `d2` be `1`.
 
 	1.  If `d1 == 1`, then
 		

From 5df75490f93609dd6c2feb2bfd205eb489c000e0 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Tue, 4 Aug 2020 14:42:29 -0700
Subject: [PATCH 29/67] Rephrase

---
 spec/API_specification/broadcasting.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/API_specification/broadcasting.md b/spec/API_specification/broadcasting.md
index 42f897aed..6a5aa0406 100644
--- a/spec/API_specification/broadcasting.md
+++ b/spec/API_specification/broadcasting.md
@@ -6,7 +6,7 @@
 
 **Broadcasting** refers to the automatic (implicit) expansion of array dimensions to be of equal sizes without copying array data for the purpose of making arrays with different shapes have compatible shapes for element-wise operations.
 
-Broadcasting facilitates user ergonomics by encouraging users to elide unnecessary copying of array data and can **potentially** enable more memory-efficient element-wise operations through vectorization, reduced memory consumption, and cache locality.
+Broadcasting facilitates user ergonomics by encouraging users to avoid unnecessary copying of array data and can **potentially** enable more memory-efficient element-wise operations through vectorization, reduced memory consumption, and cache locality.
 
 ## Algorithm
 

From 3dd72888ce59706d78cc1d6d4f6030d699f14c0e Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Tue, 4 Aug 2020 14:43:41 -0700
Subject: [PATCH 30/67] Add clause

---
 spec/API_specification/broadcasting.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/API_specification/broadcasting.md b/spec/API_specification/broadcasting.md
index 6a5aa0406..04f2a98d8 100644
--- a/spec/API_specification/broadcasting.md
+++ b/spec/API_specification/broadcasting.md
@@ -102,4 +102,4 @@ B      (3d array):  8 x 4 x 3 # second dimension does not match
 
 ## In-place Semantics
 
-In-place element-wise operations must not change the shape of the in-place array as a result of broadcasting.
\ No newline at end of file
+As implied by the broadcasting algorithm, in-place element-wise operations must not change the shape of the in-place array as a result of broadcasting.
\ No newline at end of file

From f599e2e4e6ca0fad2490f9922ade11b3e22528fe Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Wed, 5 Aug 2020 15:32:28 -0700
Subject: [PATCH 31/67] Add initial typing

---
 spec/API_specification/elementwise_functions.md | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index 6b1c3056e..609b97129 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -12,7 +12,7 @@ A conforming implementation of the array API standard must provide and support t
 
 <!-- NOTE: please keep the functions in alphabetical order -->
 
-### <a name="abs" href="#abs">#</a> abs(x, /, *, out=None)
+### <a name="abs" href="#abs">#</a> abs(x: array, /, *, out: Union\[Tuple\[array], None] = None)
 
 Calculates the absolute value for each element `x_i` of the input array `x` (i.e., the element-wise result has the same magnitude as the respective element in `x` but has positive sign).
 
@@ -22,12 +22,19 @@ Calculates the absolute value for each element `x_i` of the input array `x` (i.e
 
 #### Parameters
 
--   **x**: input array.
--   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+-   **x**: array
+
+    -   input array.
+
+-   **out**: Union\[Tuple\[array], None] (optional)
+
+    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: an array containing the absolute value of each element in `x`.
+-   **out**: array
+
+    -   an array containing the absolute value of each element in `x`.
 
 ### <a name="acos" href="#acos">#</a> acos(x, /, *, out=None)
 

From 7c34785486507dc3f116595fff1dbd3528c7efb5 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Wed, 5 Aug 2020 15:34:16 -0700
Subject: [PATCH 32/67] Remove typing from signature

---
 spec/API_specification/elementwise_functions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index 609b97129..2d343e734 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -12,7 +12,7 @@ A conforming implementation of the array API standard must provide and support t
 
 <!-- NOTE: please keep the functions in alphabetical order -->
 
-### <a name="abs" href="#abs">#</a> abs(x: array, /, *, out: Union\[Tuple\[array], None] = None)
+### <a name="abs" href="#abs">#</a> abs(x, /, *, out=None)
 
 Calculates the absolute value for each element `x_i` of the input array `x` (i.e., the element-wise result has the same magnitude as the respective element in `x` but has positive sign).
 

From 11fa322999ca980dbc38e62308d3c1b0a506e6a4 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Wed, 5 Aug 2020 15:58:47 -0700
Subject: [PATCH 33/67] Update typing

---
 spec/API_specification/elementwise_functions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index 2d343e734..e2a280d5c 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -26,7 +26,7 @@ Calculates the absolute value for each element `x_i` of the input array `x` (i.e
 
     -   input array.
 
--   **out**: Union\[Tuple\[array], None] (optional)
+-   **out**: Optional\[Tuple\[array]]
 
     -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 

From 8701e7d3d6a9cb35a149d11ad2666ee9169119c2 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Wed, 5 Aug 2020 15:59:34 -0700
Subject: [PATCH 34/67] Add markup

---
 spec/API_specification/elementwise_functions.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index e2a280d5c..56cec56a9 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -22,11 +22,11 @@ Calculates the absolute value for each element `x_i` of the input array `x` (i.e
 
 #### Parameters
 
--   **x**: array
+-   **x**: _array_
 
     -   input array.
 
--   **out**: Optional\[Tuple\[array]]
+-   **out**: _Optional\[Tuple\[array]]_
 
     -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 

From 0c27737a4f52d6355238647be859c3050071dedb Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Wed, 5 Aug 2020 16:01:18 -0700
Subject: [PATCH 35/67] Update typing

---
 spec/API_specification/elementwise_functions.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index 56cec56a9..d4f642595 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -22,17 +22,17 @@ Calculates the absolute value for each element `x_i` of the input array `x` (i.e
 
 #### Parameters
 
--   **x**: _array_
+-   **x**: _&lt;array&gt;_
 
     -   input array.
 
--   **out**: _Optional\[Tuple\[array]]_
+-   **out**: _Optional\[Tuple\[&lt;array&gt;]]_
 
     -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: array
+-   **out**: _&lt;array&gt;_
 
     -   an array containing the absolute value of each element in `x`.
 

From 7f00d0326a16afe7ee55b8afd16b308caeaa6e05 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Wed, 5 Aug 2020 16:02:05 -0700
Subject: [PATCH 36/67] Update formatting

---
 spec/API_specification/elementwise_functions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index d4f642595..736b7d960 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -26,7 +26,7 @@ Calculates the absolute value for each element `x_i` of the input array `x` (i.e
 
     -   input array.
 
--   **out**: _Optional\[Tuple\[&lt;array&gt;]]_
+-   **out**: _Optional\[ Tuple\[ &lt;array&gt; ] ]_
 
     -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 

From 21ee999ebcb2a53204e5ac43988ae22f66cc1d37 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Wed, 5 Aug 2020 16:03:13 -0700
Subject: [PATCH 37/67] Remove spaces

---
 spec/API_specification/elementwise_functions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index 736b7d960..9e2b4dac6 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -26,7 +26,7 @@ Calculates the absolute value for each element `x_i` of the input array `x` (i.e
 
     -   input array.
 
--   **out**: _Optional\[ Tuple\[ &lt;array&gt; ] ]_
+-   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
 
     -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 

From 88830260bdbe541f757009009abcfc5778b080f3 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Wed, 5 Aug 2020 16:49:59 -0700
Subject: [PATCH 38/67] Add types

---
 .../elementwise_functions.md                  | 319 ++++++++++++++----
 1 file changed, 246 insertions(+), 73 deletions(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index 9e2b4dac6..59e80cb16 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -47,12 +47,19 @@ Calculates an implementation-dependent approximation of the principal value of t
 
 #### Parameters
 
--   **x**: input array.
--   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+-   **x**: _&lt;array&gt;_
+
+    -   input array.
+
+-   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+
+    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: an array containing the inverse cosine of each element in `x`.
+-   **out**: _&lt;array&gt;_
+
+    -   an array containing the inverse cosine of each element in `x`.
 
 ### <a name="acosh" href="#acosh">#</a> acosh(x, /, *, out=None)
 
@@ -65,12 +72,19 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic c
 
 #### Parameters
 
--   **x**: input array whose elements each represent the area of a hyperbolic sector.
--   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+-   **x**: _&lt;array&gt;_
+
+    -   input array whose elements each represent the area of a hyperbolic sector.
+
+-   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+
+    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: an array containing the inverse hyperbolic cosine of each element in `x`.
+-   **out**: _&lt;array&gt;_
+
+    -   an array containing the inverse hyperbolic cosine of each element in `x`.
 
 ### <a name="add" href="#add">#</a> add(x1, x2, /, *, out=None)
 
@@ -80,13 +94,23 @@ Calculates the sum for each element <code>x1<sub>i</sub></code> of the input arr
 
 #### Parameters
 
--   **x1**: input array.
--   **x2**: input array.
--   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+-   **x1**: _&lt;array&gt;_
+
+    -   input array.
+
+-   **x2**: _&lt;array&gt;_
+
+    -   input array.
+
+-   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+
+    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: an array containing the element-wise sums.
+-   **out**: _&lt;array&gt;_
+
+    -   an array containing the element-wise sums.
 
 ### <a name="asin" href="#asin">#</a> asin(x, /, *, out=None)
 
@@ -100,12 +124,19 @@ Calculates an implementation-dependent approximation of the principal value of t
 
 #### Parameters
 
--   **x**: input array.
--   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+-   **x**: _&lt;array&gt;_
+
+    -   input array.
+
+-   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+
+    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: an array containing the inverse sine of each element in `x`.
+-   **out**: _&lt;array&gt;_
+
+    -   an array containing the inverse sine of each element in `x`.
 
 ### <a name="asinh" href="#asinh">#</a> asinh(x, /, *, out=None)
 
@@ -119,12 +150,19 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic s
 
 #### Parameters
 
--   **x**: input array whose elements each represent the area of a hyperbolic sector.
--   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+-   **x**: _&lt;array&gt;_
+
+    -   input array whose elements each represent the area of a hyperbolic sector.
+
+-   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+
+    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: an array containing the inverse hyperbolic sine of each element in `x`.
+-   **out**: _&lt;array&gt;_
+
+    -   an array containing the inverse hyperbolic sine of each element in `x`.
 
 ### <a name="atan" href="#atan">#</a> atan(x, /, *, out=None)
 
@@ -138,12 +176,19 @@ Calculates an implementation-dependent approximation of the principal value of t
 
 #### Parameters
 
--   **x**: input array.
--   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+-   **x**: _&lt;array&gt;_
+
+    -   input array.
+
+-   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+
+    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: an array containing the inverse tangent of each element in `x`.
+-   **out**: _&lt;array&gt;_
+
+    -   an array containing the inverse tangent of each element in `x`.
 
 ### <a name="atanh" href="#atanh">#</a> atanh(x, /, *, out=None)
 
@@ -159,12 +204,19 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic t
 
 #### Parameters
 
--   **x**: input array whose elements each represent the area of a hyperbolic sector.
--   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+-   **x**: _&lt;array&gt;_
+
+    -   input array whose elements each represent the area of a hyperbolic sector.
+
+-   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+
+    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: an array containing the inverse hyperbolic tangent of each element in `x`.
+-   **out**: _&lt;array&gt;_
+
+    -   an array containing the inverse hyperbolic tangent of each element in `x`.
 
 ### <a name="ceil" href="#ceil">#</a> ceil(x, /, *, out=None)
 
@@ -174,12 +226,19 @@ Rounds each element `x_i` of the input array `x` to the smallest (i.e., closest
 
 #### Parameters
 
--   **x**: input array.
--   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+-   **x**: _&lt;array&gt;_
+
+    -   input array.
+
+-   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+
+    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: an array containing the rounded result for each element in `x`.
+-   **out**: _&lt;array&gt;_
+
+    -   an array containing the rounded result for each element in `x`.
 
 ### <a name="cos" href="#cos">#</a> cos(x, /, *, out=None)
 
@@ -193,12 +252,19 @@ Calculates an implementation-dependent approximation to the cosine, having domai
 
 #### Parameters
 
--   **x**: input array whose elements are each expressed in radians.
--   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+-   **x**: _&lt;array&gt;_
+
+    -   input array whose elements are each expressed in radians.
+
+-   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+
+    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: an array containing the cosine of each element in `x`.
+-   **out**: _&lt;array&gt;_
+
+    -   an array containing the cosine of each element in `x`.
 
 ### <a name="cosh" href="#cosh">#</a> cosh(x, /, *, out=None)
 
@@ -212,12 +278,19 @@ Calculates an implementation-dependent approximation to the hyperbolic cosine, h
 
 #### Parameters
 
--   **x**: input array whose elements each represent a hyperbolic angle.
--   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+-   **x**: _&lt;array&gt;_
+
+    -   input array whose elements each represent a hyperbolic angle.
+
+-   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+
+    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: an array containing the hyperbolic cosine of each element in `x`.
+-   **out**: _&lt;array&gt;_
+
+    -   an array containing the hyperbolic cosine of each element in `x`.
 
 ### <a name="divide" href="#divide">#</a> divide(x1, x2, /, *, out=None)
 
@@ -227,13 +300,23 @@ Calculates the division for each element <code>x1<sub>i</sub></code> of the inpu
 
 #### Parameters
 
--   **x1**: dividend input array.
--   **x2**: divisor input array.
--   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+-   **x1**: _&lt;array&gt;_
+
+    -   dividend input array.
+
+-   **x2**: _&lt;array&gt;_
+
+    -   divisor input array.
+
+-   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+
+    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: an array containing the element-wise results.
+-   **out**: _&lt;array&gt;_
+
+    -   an array containing the element-wise results.
 
 ### <a name="exp" href="#exp">#</a> exp(x, /, *, out=None)
 
@@ -247,12 +330,19 @@ Calculates an implementation-dependent approximation to the exponential function
 
 #### Parameters
 
--   **x**: input array.
--   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+-   **x**: _&lt;array&gt;_
+
+    -   input array.
+
+-   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+
+    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: an array containing the evaluated exponential function result for each element in `x`.
+-   **out**: _&lt;array&gt;_
+
+    -   an array containing the evaluated exponential function result for each element in `x`.
 
 ### <a name="floor" href="#floor">#</a> floor(x, /, *, out=None)
 
@@ -262,12 +352,19 @@ Rounds each element `x_i` of the input array `x` to the greatest (i.e., closest
 
 #### Parameters
 
--   **x**: input array.
--   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+-   **x**: _&lt;array&gt;_
+
+    -   input array.
+
+-   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+
+    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: an array containing the rounded result for each element in `x`.
+-   **out**: _&lt;array&gt;_
+
+    -   an array containing the rounded result for each element in `x`.
 
 ### <a name="log" href="#log">#</a> log(x, /, *, out=None)
 
@@ -281,12 +378,19 @@ Calculates an implementation-dependent approximation to the natural (base `e`) l
 
 #### Parameters
 
--   **x**: input array.
--   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+-   **x**: _&lt;array&gt;_
+
+    -   input array.
+
+-   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+
+    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: an array containing the evaluated natural logarithm for each element in `x`.
+-   **out**: _&lt;array&gt;_
+
+    -   an array containing the evaluated natural logarithm for each element in `x`.
 
 ### <a name="multiply" href="#multiply">#</a> multiply(x1, x2, /, *, out=None)
 
@@ -296,13 +400,23 @@ Calculates the product for each element <code>x1<sub>i</sub></code> of the input
 
 #### Parameters
 
--   **x1**: input array.
--   **x2**: input array.
--   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+-   **x1**: _&lt;array&gt;_
+
+    -   input array.
+
+-   **x2**: _&lt;array&gt;_
+
+    -   input array.
+
+-   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+
+    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: an array containing the element-wise products.
+-   **out**: _&lt;array&gt;_
+
+    -   an array containing the element-wise products.
 
 ### <a name="round" href="#round">#</a> round(x, /, *, out=None)
 
@@ -313,12 +427,19 @@ Rounds each element `x_i` of the input array `x` to the nearest integer-valued n
 
 #### Parameters
 
--   **x**: input array.
--   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+-   **x**: _&lt;array&gt;_
+
+    -   input array.
+
+-   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+
+    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: an array containing the rounded result for each element in `x`.
+-   **out**: _&lt;array&gt;_
+
+    -   an array containing the rounded result for each element in `x`.
 
 ### <a name="sin" href="#sin">#</a> sin(x, /, *, out=None)
 
@@ -331,12 +452,19 @@ Calculates an implementation-dependent approximation to the sine, having domain
 
 #### Parameters
 
--   **x**: input array whose elements are each expressed in radians.
--   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+-   **x**: _&lt;array&gt;_
+
+    -   input array whose elements are each expressed in radians.
+
+-   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+
+    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: an array containing the sine of each element in `x`.
+-   **out**: _&lt;array&gt;_
+
+    -   an array containing the sine of each element in `x`.
 
 ### <a name="sinh" href="#sinh">#</a> sinh(x, /, *, out=None)
 
@@ -350,12 +478,19 @@ Calculates an implementation-dependent approximation to the hyperbolic sine, hav
 
 #### Parameters
 
--   **x**: input array whose elements each represent a hyperbolic angle.
--   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+-   **x**: _&lt;array&gt;_
+
+    -   input array whose elements each represent a hyperbolic angle.
+
+-   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+
+    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: an array containing the hyperbolic sine of each element in `x`.
+-   **out**: _&lt;array&gt;_
+
+    -   an array containing the hyperbolic sine of each element in `x`.
 
 ### <a name="sqrt" href="#sqrt">#</a> sqrt(x, /, *, out=None)
 
@@ -369,12 +504,19 @@ Calculates the square root, having domain `[0, +infinity]` and codomain `[0, +in
 
 #### Parameters
 
--   **x**: input array.
--   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+-   **x**: _&lt;array&gt;_
+
+    -   input array.
+
+-   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+
+    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: an array containing the square root of each element in `x`.
+-   **out**: _&lt;array&gt;_
+
+    -   an array containing the square root of each element in `x`.
 
 ### <a name="subtract" href="#subtract">#</a> subtract(x1, x2, /, *, out=None)
 
@@ -384,13 +526,23 @@ Calculates the difference for each element <code>x1<sub>i</sub></code> of the in
 
 #### Parameters
 
--   **x1**: input array.
--   **x2**: input array.
--   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+-   **x1**: _&lt;array&gt;_
+
+    -   input array.
+
+-   **x2**: _&lt;array&gt;_
+
+    -   input array.
+
+-   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+
+    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: an array containing the element-wise differences.
+-   **out**: _&lt;array&gt;_
+
+    -   an array containing the element-wise differences.
 
 ### <a name="tan" href="#tan">#</a> tan(x, /, *, out=None)
 
@@ -403,12 +555,19 @@ Calculates an implementation-dependent approximation to the tangent, having doma
 
 #### Parameters
 
--   **x**: input array whose elements are each expressed in radians.
--   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+-   **x**: _&lt;array&gt;_
+
+    -   input array whose elements are each expressed in radians.
+
+-   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+
+    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: an array containing the tangent of each element in `x`.
+-   **out**: _&lt;array&gt;_
+
+    -   an array containing the tangent of each element in `x`.
 
 ### <a name="tanh" href="#tanh">#</a> tanh(x, /, *, out=None)
 
@@ -422,12 +581,19 @@ Calculates an implementation-dependent approximation to the hyperbolic tangent,
 
 #### Parameters
 
--   **x**: input array whose elements each represent a hyperbolic angle.
--   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+-   **x**: _&lt;array&gt;_
+
+    -   input array whose elements each represent a hyperbolic angle.
+
+-   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+
+    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: an array containing the hyperbolic tangent of each element in `x`.
+-   **out**: _&lt;array&gt;_
+
+    -   an array containing the hyperbolic tangent of each element in `x`.
 
 ### <a name="trunc" href="#trunc">#</a> trunc(x, /, *, out=None)
 
@@ -437,9 +603,16 @@ Rounds each element `x_i` of the input array `x` to the integer-valued number th
 
 #### Parameters
 
--   **x**: input array.
--   **out**: output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+-   **x**: _&lt;array&gt;_
+
+    -   input array.
+
+-   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+
+    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
--   **out**: an array containing the rounded result for each element in `x`.
+-   **out**: _&lt;array&gt;_
+
+    -   an array containing the rounded result for each element in `x`.

From be488d5018b6cfe8baafa73b234ad9f8c6dfa738 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Wed, 5 Aug 2020 17:11:21 -0700
Subject: [PATCH 39/67] Update `out` requirements

---
 spec/API_specification/elementwise_functions.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index 59e80cb16..be12440c4 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -6,8 +6,8 @@ A conforming implementation of the array API standard must provide and support t
 
 -   Positional parameters must be [positional-only](https://www.python.org/dev/peps/pep-0570/) parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order.
 -   Optional parameters must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments.
--   An `out` keyword argument must be a tuple with one entry per output.
--   If `out` is not provided or is `None` (the default), an uninitialized return array must be created for each output.
+-   For functions returning a single output array, the `out` keyword argument may be either `None`, an array, or a tuple containing a single array element. When a function returns multiple output arrays, the `out` keyword argument must be a tuple with one entry (either `None` or an array) per output.
+-   If `out` is not provided or is `None` (the default), an uninitialized return array must be created for each output for which an output array has not been provided.
 -   Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.
 
 <!-- NOTE: please keep the functions in alphabetical order -->
@@ -26,7 +26,7 @@ Calculates the absolute value for each element `x_i` of the input array `x` (i.e
 
     -   input array.
 
--   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+-   **out**: _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
     -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 

From 31f69db555407c0baf69428773f6c1678643d6f8 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Wed, 5 Aug 2020 17:15:50 -0700
Subject: [PATCH 40/67] Update types and descriptions

---
 .../elementwise_functions.md                  | 94 +++++++++----------
 1 file changed, 47 insertions(+), 47 deletions(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index be12440c4..495d7b29c 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -28,7 +28,7 @@ Calculates the absolute value for each element `x_i` of the input array `x` (i.e
 
 -   **out**: _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -51,9 +51,9 @@ Calculates an implementation-dependent approximation of the principal value of t
 
     -   input array.
 
--   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+-   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -76,9 +76,9 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic c
 
     -   input array whose elements each represent the area of a hyperbolic sector.
 
--   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+-   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -102,9 +102,9 @@ Calculates the sum for each element <code>x1<sub>i</sub></code> of the input arr
 
     -   input array.
 
--   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+-   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -128,9 +128,9 @@ Calculates an implementation-dependent approximation of the principal value of t
 
     -   input array.
 
--   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+-   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -154,9 +154,9 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic s
 
     -   input array whose elements each represent the area of a hyperbolic sector.
 
--   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+-   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -180,9 +180,9 @@ Calculates an implementation-dependent approximation of the principal value of t
 
     -   input array.
 
--   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+-   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -208,9 +208,9 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic t
 
     -   input array whose elements each represent the area of a hyperbolic sector.
 
--   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+-   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -230,9 +230,9 @@ Rounds each element `x_i` of the input array `x` to the smallest (i.e., closest
 
     -   input array.
 
--   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+-   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -256,9 +256,9 @@ Calculates an implementation-dependent approximation to the cosine, having domai
 
     -   input array whose elements are each expressed in radians.
 
--   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+-   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -282,9 +282,9 @@ Calculates an implementation-dependent approximation to the hyperbolic cosine, h
 
     -   input array whose elements each represent a hyperbolic angle.
 
--   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+-   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -308,9 +308,9 @@ Calculates the division for each element <code>x1<sub>i</sub></code> of the inpu
 
     -   divisor input array.
 
--   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+-   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -334,9 +334,9 @@ Calculates an implementation-dependent approximation to the exponential function
 
     -   input array.
 
--   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+-   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -356,9 +356,9 @@ Rounds each element `x_i` of the input array `x` to the greatest (i.e., closest
 
     -   input array.
 
--   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+-   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -382,9 +382,9 @@ Calculates an implementation-dependent approximation to the natural (base `e`) l
 
     -   input array.
 
--   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+-   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -408,9 +408,9 @@ Calculates the product for each element <code>x1<sub>i</sub></code> of the input
 
     -   input array.
 
--   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+-   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -431,9 +431,9 @@ Rounds each element `x_i` of the input array `x` to the nearest integer-valued n
 
     -   input array.
 
--   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+-   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -456,9 +456,9 @@ Calculates an implementation-dependent approximation to the sine, having domain
 
     -   input array whose elements are each expressed in radians.
 
--   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+-   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -482,9 +482,9 @@ Calculates an implementation-dependent approximation to the hyperbolic sine, hav
 
     -   input array whose elements each represent a hyperbolic angle.
 
--   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+-   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -508,9 +508,9 @@ Calculates the square root, having domain `[0, +infinity]` and codomain `[0, +in
 
     -   input array.
 
--   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+-   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -534,9 +534,9 @@ Calculates the difference for each element <code>x1<sub>i</sub></code> of the in
 
     -   input array.
 
--   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+-   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -559,9 +559,9 @@ Calculates an implementation-dependent approximation to the tangent, having doma
 
     -   input array whose elements are each expressed in radians.
 
--   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+-   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -585,9 +585,9 @@ Calculates an implementation-dependent approximation to the hyperbolic tangent,
 
     -   input array whose elements each represent a hyperbolic angle.
 
--   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+-   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -607,9 +607,9 @@ Rounds each element `x_i` of the input array `x` to the integer-valued number th
 
     -   input array.
 
--   **out**: _Optional\[ Tuple\[&lt;array&gt;] ]_
+-   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If provided, must be a tuple consisting of a single value: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 

From 8194b381e150ea0b55faa1c50fa9e05ee8641062 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Wed, 5 Aug 2020 17:18:38 -0700
Subject: [PATCH 41/67] Update descriptions

---
 .../elementwise_functions.md                  | 48 +++++++++----------
 1 file changed, 24 insertions(+), 24 deletions(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index 495d7b29c..164dd3840 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -28,7 +28,7 @@ Calculates the absolute value for each element `x_i` of the input array `x` (i.e
 
 -   **out**: _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -53,7 +53,7 @@ Calculates an implementation-dependent approximation of the principal value of t
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -78,7 +78,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic c
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -104,7 +104,7 @@ Calculates the sum for each element <code>x1<sub>i</sub></code> of the input arr
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -130,7 +130,7 @@ Calculates an implementation-dependent approximation of the principal value of t
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -156,7 +156,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic s
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -182,7 +182,7 @@ Calculates an implementation-dependent approximation of the principal value of t
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -210,7 +210,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic t
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -232,7 +232,7 @@ Rounds each element `x_i` of the input array `x` to the smallest (i.e., closest
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -258,7 +258,7 @@ Calculates an implementation-dependent approximation to the cosine, having domai
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -284,7 +284,7 @@ Calculates an implementation-dependent approximation to the hyperbolic cosine, h
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -310,7 +310,7 @@ Calculates the division for each element <code>x1<sub>i</sub></code> of the inpu
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -336,7 +336,7 @@ Calculates an implementation-dependent approximation to the exponential function
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -358,7 +358,7 @@ Rounds each element `x_i` of the input array `x` to the greatest (i.e., closest
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -384,7 +384,7 @@ Calculates an implementation-dependent approximation to the natural (base `e`) l
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -410,7 +410,7 @@ Calculates the product for each element <code>x1<sub>i</sub></code> of the input
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -433,7 +433,7 @@ Rounds each element `x_i` of the input array `x` to the nearest integer-valued n
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -458,7 +458,7 @@ Calculates an implementation-dependent approximation to the sine, having domain
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -484,7 +484,7 @@ Calculates an implementation-dependent approximation to the hyperbolic sine, hav
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -510,7 +510,7 @@ Calculates the square root, having domain `[0, +infinity]` and codomain `[0, +in
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -536,7 +536,7 @@ Calculates the difference for each element <code>x1<sub>i</sub></code> of the in
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -561,7 +561,7 @@ Calculates an implementation-dependent approximation to the tangent, having doma
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -587,7 +587,7 @@ Calculates an implementation-dependent approximation to the hyperbolic tangent,
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -609,7 +609,7 @@ Rounds each element `x_i` of the input array `x` to the integer-valued number th
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If a tuple, must consist of a single entry: the output array or `None`. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 

From 6100447888153fcd0c3d734880f68600e4d9e31e Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Wed, 5 Aug 2020 17:21:45 -0700
Subject: [PATCH 42/67] Update conventions

---
 spec/API_specification/elementwise_functions.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index 164dd3840..48696d936 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -6,7 +6,8 @@ A conforming implementation of the array API standard must provide and support t
 
 -   Positional parameters must be [positional-only](https://www.python.org/dev/peps/pep-0570/) parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order.
 -   Optional parameters must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments.
--   For functions returning a single output array, the `out` keyword argument may be either `None`, an array, or a tuple containing a single array element. When a function returns multiple output arrays, the `out` keyword argument must be a tuple with one entry (either `None` or an array) per output.
+-   For functions returning a single output array, the `out` keyword argument may be either `None`, an array, or a tuple containing a single array element.
+-   When a function returns multiple output arrays, the `out` keyword argument must be a tuple with one entry (either `None` or an array) per output. Providing a single output array when a function returns multiple output arrays must **not** be permitted.
 -   If `out` is not provided or is `None` (the default), an uninitialized return array must be created for each output for which an output array has not been provided.
 -   Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.
 

From 8890def91dfc3b8f05f0bd27622917cfe8ce7a1b Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Wed, 5 Aug 2020 17:25:52 -0700
Subject: [PATCH 43/67] Remove markup and update descriptions

---
 .../elementwise_functions.md                  | 28 +++++++++----------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index 48696d936..ff57d3758 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -89,19 +89,19 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic c
 
 ### <a name="add" href="#add">#</a> add(x1, x2, /, *, out=None)
 
-Calculates the sum for each element <code>x1<sub>i</sub></code> of the input array `x1` with the respective element <code>x2<sub>i</sub></code> of the input array `x2`.
+Calculates the sum for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`.
 
--   If either <code>x1<sub>i</sub></code> or <code>x2<sub>i</sub></code> is `NaN`, the result is `NaN`.
+-   If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`.
 
 #### Parameters
 
 -   **x1**: _&lt;array&gt;_
 
-    -   input array.
+    -   first input array.
 
 -   **x2**: _&lt;array&gt;_
 
-    -   input array.
+    -   second input array.
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
@@ -295,9 +295,9 @@ Calculates an implementation-dependent approximation to the hyperbolic cosine, h
 
 ### <a name="divide" href="#divide">#</a> divide(x1, x2, /, *, out=None)
 
-Calculates the division for each element <code>x1<sub>i</sub></code> of the input array `x1` with the respective element <code>x2<sub>i</sub></code> of the input array `x2`.
+Calculates the division for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`.
 
--   If either <code>x1<sub>i</sub></code> or <code>x2<sub>i</sub></code> is `NaN`, the result is `NaN`.
+-   If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`.
 
 #### Parameters
 
@@ -395,19 +395,19 @@ Calculates an implementation-dependent approximation to the natural (base `e`) l
 
 ### <a name="multiply" href="#multiply">#</a> multiply(x1, x2, /, *, out=None)
 
-Calculates the product for each element <code>x1<sub>i</sub></code> of the input array `x1` with the respective element <code>x2<sub>i</sub></code> of the input array `x2`.
+Calculates the product for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`.
 
--   If either <code>x1<sub>i</sub></code> or <code>x2<sub>i</sub></code> is `NaN`, the result is `NaN`.
+-   If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`.
 
 #### Parameters
 
 -   **x1**: _&lt;array&gt;_
 
-    -   input array.
+    -   first input array.
 
 -   **x2**: _&lt;array&gt;_
 
-    -   input array.
+    -   second input array.
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
@@ -521,19 +521,19 @@ Calculates the square root, having domain `[0, +infinity]` and codomain `[0, +in
 
 ### <a name="subtract" href="#subtract">#</a> subtract(x1, x2, /, *, out=None)
 
-Calculates the difference for each element <code>x1<sub>i</sub></code> of the input array `x1` with the respective element <code>x2<sub>i</sub></code> of the input array `x2`.
+Calculates the difference for each element `x1_i` of the input array `x1` with the respective element `x2_i` of the input array `x2`.
 
--   If either <code>x1<sub>i</sub></code> or <code>x2<sub>i</sub></code> is `NaN`, the result is `NaN`.
+-   If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`.
 
 #### Parameters
 
 -   **x1**: _&lt;array&gt;_
 
-    -   input array.
+    -   first input array.
 
 -   **x2**: _&lt;array&gt;_
 
-    -   input array.
+    -   second input array.
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 

From b489749de9bae13d34c3860a6f1dcf93a3a5d7ec Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Wed, 5 Aug 2020 17:59:30 -0700
Subject: [PATCH 44/67] Document broadcasting behavior

---
 .../elementwise_functions.md                  | 57 ++++++++++---------
 1 file changed, 29 insertions(+), 28 deletions(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index ff57d3758..eae43beed 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -9,6 +9,7 @@ A conforming implementation of the array API standard must provide and support t
 -   For functions returning a single output array, the `out` keyword argument may be either `None`, an array, or a tuple containing a single array element.
 -   When a function returns multiple output arrays, the `out` keyword argument must be a tuple with one entry (either `None` or an array) per output. Providing a single output array when a function returns multiple output arrays must **not** be permitted.
 -   If `out` is not provided or is `None` (the default), an uninitialized return array must be created for each output for which an output array has not been provided.
+-   Broadcasting semantics must follow the semantics defined by this specification.
 -   Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.
 
 <!-- NOTE: please keep the functions in alphabetical order -->
@@ -29,7 +30,7 @@ Calculates the absolute value for each element `x_i` of the input array `x` (i.e
 
 -   **out**: _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -54,7 +55,7 @@ Calculates an implementation-dependent approximation of the principal value of t
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -79,7 +80,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic c
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -101,11 +102,11 @@ Calculates the sum for each element `x1_i` of the input array `x1` with the resp
 
 -   **x2**: _&lt;array&gt;_
 
-    -   second input array.
+    -   second input array. Must be compatible with `x1` (i.e., `x1` and `x2` must be able to broadcast to a common shape). 
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input arrays (i.e., must have a shape to which the input arrays can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -131,7 +132,7 @@ Calculates an implementation-dependent approximation of the principal value of t
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -157,7 +158,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic s
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -183,7 +184,7 @@ Calculates an implementation-dependent approximation of the principal value of t
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -211,7 +212,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic t
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -233,7 +234,7 @@ Rounds each element `x_i` of the input array `x` to the smallest (i.e., closest
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -259,7 +260,7 @@ Calculates an implementation-dependent approximation to the cosine, having domai
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -285,7 +286,7 @@ Calculates an implementation-dependent approximation to the hyperbolic cosine, h
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -307,11 +308,11 @@ Calculates the division for each element `x1_i` of the input array `x1` with the
 
 -   **x2**: _&lt;array&gt;_
 
-    -   divisor input array.
+    -   divisor input array. Must be compatible with `x1` (i.e., `x1` and `x2` must be able to broadcast to a common shape).
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input arrays (i.e., must have a shape to which the input arrays can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -337,7 +338,7 @@ Calculates an implementation-dependent approximation to the exponential function
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -359,7 +360,7 @@ Rounds each element `x_i` of the input array `x` to the greatest (i.e., closest
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -385,7 +386,7 @@ Calculates an implementation-dependent approximation to the natural (base `e`) l
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -407,11 +408,11 @@ Calculates the product for each element `x1_i` of the input array `x1` with the
 
 -   **x2**: _&lt;array&gt;_
 
-    -   second input array.
+    -   second input array. Must be compatible with `x1` (i.e., `x1` and `x2` must be able to broadcast to a common shape).
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input arrays (i.e., must have a shape to which the input arrays can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -434,7 +435,7 @@ Rounds each element `x_i` of the input array `x` to the nearest integer-valued n
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -459,7 +460,7 @@ Calculates an implementation-dependent approximation to the sine, having domain
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -485,7 +486,7 @@ Calculates an implementation-dependent approximation to the hyperbolic sine, hav
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -511,7 +512,7 @@ Calculates the square root, having domain `[0, +infinity]` and codomain `[0, +in
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -533,11 +534,11 @@ Calculates the difference for each element `x1_i` of the input array `x1` with t
 
 -   **x2**: _&lt;array&gt;_
 
-    -   second input array.
+    -   second input array. Must be compatible with `x1` (i.e., `x1` and `x2` must be able to broadcast to a common shape).
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input arrays (i.e., must have a shape to which the input arrays can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -562,7 +563,7 @@ Calculates an implementation-dependent approximation to the tangent, having doma
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -588,7 +589,7 @@ Calculates an implementation-dependent approximation to the hyperbolic tangent,
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -610,7 +611,7 @@ Rounds each element `x_i` of the input array `x` to the integer-valued number th
 
 -   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
 
-    -   output array. If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 

From 4af802c7a49b1b4d9e26d55f325273464271605e Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Wed, 5 Aug 2020 18:00:21 -0700
Subject: [PATCH 45/67] Update wording

---
 spec/API_specification/elementwise_functions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index eae43beed..6370192b1 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -9,7 +9,7 @@ A conforming implementation of the array API standard must provide and support t
 -   For functions returning a single output array, the `out` keyword argument may be either `None`, an array, or a tuple containing a single array element.
 -   When a function returns multiple output arrays, the `out` keyword argument must be a tuple with one entry (either `None` or an array) per output. Providing a single output array when a function returns multiple output arrays must **not** be permitted.
 -   If `out` is not provided or is `None` (the default), an uninitialized return array must be created for each output for which an output array has not been provided.
--   Broadcasting semantics must follow the semantics defined by this specification.
+-   Broadcasting semantics must follow the semantics defined in this specification.
 -   Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.
 
 <!-- NOTE: please keep the functions in alphabetical order -->

From f8ef97f02314ec3567806c47dbba023bf77e1279 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Wed, 5 Aug 2020 18:05:36 -0700
Subject: [PATCH 46/67] Rephrase

---
 spec/API_specification/elementwise_functions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index 6370192b1..8f33f7375 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -6,7 +6,7 @@ A conforming implementation of the array API standard must provide and support t
 
 -   Positional parameters must be [positional-only](https://www.python.org/dev/peps/pep-0570/) parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order.
 -   Optional parameters must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments.
--   For functions returning a single output array, the `out` keyword argument may be either `None`, an array, or a tuple containing a single array element.
+-   For functions returning a single output array, the `out` keyword argument may be either `None`, an array, or a tuple consisting of a single array as its only entry.
 -   When a function returns multiple output arrays, the `out` keyword argument must be a tuple with one entry (either `None` or an array) per output. Providing a single output array when a function returns multiple output arrays must **not** be permitted.
 -   If `out` is not provided or is `None` (the default), an uninitialized return array must be created for each output for which an output array has not been provided.
 -   Broadcasting semantics must follow the semantics defined in this specification.

From c4847d1e669f70069911415b354a4d9924dcfac6 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Thu, 6 Aug 2020 09:13:03 -0700
Subject: [PATCH 47/67] Add example

---
 spec/API_specification/broadcasting.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/spec/API_specification/broadcasting.md b/spec/API_specification/broadcasting.md
index 04f2a98d8..6364f0ba4 100644
--- a/spec/API_specification/broadcasting.md
+++ b/spec/API_specification/broadcasting.md
@@ -94,10 +94,13 @@ The following examples demonstrate array shapes which do **not** broadcast.
 
 ```text
 A      (1d array):  3
-B      (1d array):  4 # dimension does not match
+B      (1d array):  4           # dimension does not match
 
 A      (2d array):      2 x 1
-B      (3d array):  8 x 4 x 3 # second dimension does not match
+B      (3d array):  8 x 4 x 3   # second dimension does not match
+
+A      (3d array):  15 x 3 x 5
+B      (2d array):  15 x 3      # size-1 dimensions can only be prepended, not appended
 ```
 
 ## In-place Semantics

From 18738cf85ea33c3ecb35fece4c47b199cf3797e4 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Fri, 7 Aug 2020 14:02:39 -0700
Subject: [PATCH 48/67] Update `out` type

---
 .../elementwise_functions.md                  | 48 +++++++++----------
 1 file changed, 24 insertions(+), 24 deletions(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index 8f33f7375..b3fad6171 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -28,7 +28,7 @@ Calculates the absolute value for each element `x_i` of the input array `x` (i.e
 
     -   input array.
 
--   **out**: _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
+-   **out**: _Optional\[ &lt;array&gt; ]_
 
     -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
@@ -53,7 +53,7 @@ Calculates an implementation-dependent approximation of the principal value of t
 
     -   input array.
 
--   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
+-   **out**:  _Optional\[ &lt;array&gt; ]_
 
     -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
@@ -78,7 +78,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic c
 
     -   input array whose elements each represent the area of a hyperbolic sector.
 
--   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
+-   **out**:  _Optional\[ &lt;array&gt; ]_
 
     -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
@@ -104,7 +104,7 @@ Calculates the sum for each element `x1_i` of the input array `x1` with the resp
 
     -   second input array. Must be compatible with `x1` (i.e., `x1` and `x2` must be able to broadcast to a common shape). 
 
--   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
+-   **out**:  _Optional\[ &lt;array&gt; ]_
 
     -   output array. If provided, the output array must be compatible with the provided input arrays (i.e., must have a shape to which the input arrays can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
@@ -130,7 +130,7 @@ Calculates an implementation-dependent approximation of the principal value of t
 
     -   input array.
 
--   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
+-   **out**:  _Optional\[ &lt;array&gt; ]_
 
     -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
@@ -156,7 +156,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic s
 
     -   input array whose elements each represent the area of a hyperbolic sector.
 
--   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
+-   **out**:  _Optional\[ &lt;array&gt; ]_
 
     -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
@@ -182,7 +182,7 @@ Calculates an implementation-dependent approximation of the principal value of t
 
     -   input array.
 
--   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
+-   **out**:  _Optional\[ &lt;array&gt; ]_
 
     -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
@@ -210,7 +210,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic t
 
     -   input array whose elements each represent the area of a hyperbolic sector.
 
--   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
+-   **out**:  _Optional\[ &lt;array&gt; ]_
 
     -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
@@ -232,7 +232,7 @@ Rounds each element `x_i` of the input array `x` to the smallest (i.e., closest
 
     -   input array.
 
--   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
+-   **out**:  _Optional\[ &lt;array&gt; ]_
 
     -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
@@ -258,7 +258,7 @@ Calculates an implementation-dependent approximation to the cosine, having domai
 
     -   input array whose elements are each expressed in radians.
 
--   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
+-   **out**:  _Optional\[ &lt;array&gt; ]_
 
     -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
@@ -284,7 +284,7 @@ Calculates an implementation-dependent approximation to the hyperbolic cosine, h
 
     -   input array whose elements each represent a hyperbolic angle.
 
--   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
+-   **out**:  _Optional\[ &lt;array&gt; ]_
 
     -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
@@ -310,7 +310,7 @@ Calculates the division for each element `x1_i` of the input array `x1` with the
 
     -   divisor input array. Must be compatible with `x1` (i.e., `x1` and `x2` must be able to broadcast to a common shape).
 
--   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
+-   **out**:  _Optional\[ &lt;array&gt; ]_
 
     -   output array. If provided, the output array must be compatible with the provided input arrays (i.e., must have a shape to which the input arrays can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
@@ -336,7 +336,7 @@ Calculates an implementation-dependent approximation to the exponential function
 
     -   input array.
 
--   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
+-   **out**:  _Optional\[ &lt;array&gt; ]_
 
     -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
@@ -358,7 +358,7 @@ Rounds each element `x_i` of the input array `x` to the greatest (i.e., closest
 
     -   input array.
 
--   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
+-   **out**:  _Optional\[ &lt;array&gt; ]_
 
     -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
@@ -384,7 +384,7 @@ Calculates an implementation-dependent approximation to the natural (base `e`) l
 
     -   input array.
 
--   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
+-   **out**:  _Optional\[ &lt;array&gt; ]_
 
     -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
@@ -410,7 +410,7 @@ Calculates the product for each element `x1_i` of the input array `x1` with the
 
     -   second input array. Must be compatible with `x1` (i.e., `x1` and `x2` must be able to broadcast to a common shape).
 
--   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
+-   **out**:  _Optional\[ &lt;array&gt; ]_
 
     -   output array. If provided, the output array must be compatible with the provided input arrays (i.e., must have a shape to which the input arrays can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
@@ -433,7 +433,7 @@ Rounds each element `x_i` of the input array `x` to the nearest integer-valued n
 
     -   input array.
 
--   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
+-   **out**:  _Optional\[ &lt;array&gt; ]_
 
     -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
@@ -458,7 +458,7 @@ Calculates an implementation-dependent approximation to the sine, having domain
 
     -   input array whose elements are each expressed in radians.
 
--   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
+-   **out**:  _Optional\[ &lt;array&gt; ]_
 
     -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
@@ -484,7 +484,7 @@ Calculates an implementation-dependent approximation to the hyperbolic sine, hav
 
     -   input array whose elements each represent a hyperbolic angle.
 
--   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
+-   **out**:  _Optional\[ &lt;array&gt; ]_
 
     -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
@@ -510,7 +510,7 @@ Calculates the square root, having domain `[0, +infinity]` and codomain `[0, +in
 
     -   input array.
 
--   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
+-   **out**:  _Optional\[ &lt;array&gt; ]_
 
     -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
@@ -536,7 +536,7 @@ Calculates the difference for each element `x1_i` of the input array `x1` with t
 
     -   second input array. Must be compatible with `x1` (i.e., `x1` and `x2` must be able to broadcast to a common shape).
 
--   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
+-   **out**:  _Optional\[ &lt;array&gt; ]_
 
     -   output array. If provided, the output array must be compatible with the provided input arrays (i.e., must have a shape to which the input arrays can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
@@ -561,7 +561,7 @@ Calculates an implementation-dependent approximation to the tangent, having doma
 
     -   input array whose elements are each expressed in radians.
 
--   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
+-   **out**:  _Optional\[ &lt;array&gt; ]_
 
     -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
@@ -587,7 +587,7 @@ Calculates an implementation-dependent approximation to the hyperbolic tangent,
 
     -   input array whose elements each represent a hyperbolic angle.
 
--   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
+-   **out**:  _Optional\[ &lt;array&gt; ]_
 
     -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
@@ -609,7 +609,7 @@ Rounds each element `x_i` of the input array `x` to the integer-valued number th
 
     -   input array.
 
--   **out**:  _Optional\[ Union\[ &lt;array&gt;, Tuple\[ Optional\[&lt;array&gt;] ] ]_
+-   **out**:  _Optional\[ &lt;array&gt; ]_
 
     -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 

From 29a6a5de5dae73bc475f8e7aa0f6acdd4ded7fcc Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Fri, 7 Aug 2020 14:04:49 -0700
Subject: [PATCH 49/67] Update descriptions

---
 .../elementwise_functions.md                  | 48 +++++++++----------
 1 file changed, 24 insertions(+), 24 deletions(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index b3fad6171..ec3b72b4d 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -30,7 +30,7 @@ Calculates the absolute value for each element `x_i` of the input array `x` (i.e
 
 -   **out**: _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -55,7 +55,7 @@ Calculates an implementation-dependent approximation of the principal value of t
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -80,7 +80,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic c
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -106,7 +106,7 @@ Calculates the sum for each element `x1_i` of the input array `x1` with the resp
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input arrays (i.e., must have a shape to which the input arrays can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input arrays (i.e., must have a shape to which the input arrays can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -132,7 +132,7 @@ Calculates an implementation-dependent approximation of the principal value of t
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -158,7 +158,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic s
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -184,7 +184,7 @@ Calculates an implementation-dependent approximation of the principal value of t
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -212,7 +212,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic t
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -234,7 +234,7 @@ Rounds each element `x_i` of the input array `x` to the smallest (i.e., closest
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -260,7 +260,7 @@ Calculates an implementation-dependent approximation to the cosine, having domai
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -286,7 +286,7 @@ Calculates an implementation-dependent approximation to the hyperbolic cosine, h
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -312,7 +312,7 @@ Calculates the division for each element `x1_i` of the input array `x1` with the
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input arrays (i.e., must have a shape to which the input arrays can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input arrays (i.e., must have a shape to which the input arrays can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -338,7 +338,7 @@ Calculates an implementation-dependent approximation to the exponential function
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -360,7 +360,7 @@ Rounds each element `x_i` of the input array `x` to the greatest (i.e., closest
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -386,7 +386,7 @@ Calculates an implementation-dependent approximation to the natural (base `e`) l
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -412,7 +412,7 @@ Calculates the product for each element `x1_i` of the input array `x1` with the
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input arrays (i.e., must have a shape to which the input arrays can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input arrays (i.e., must have a shape to which the input arrays can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -435,7 +435,7 @@ Rounds each element `x_i` of the input array `x` to the nearest integer-valued n
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -460,7 +460,7 @@ Calculates an implementation-dependent approximation to the sine, having domain
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -486,7 +486,7 @@ Calculates an implementation-dependent approximation to the hyperbolic sine, hav
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -512,7 +512,7 @@ Calculates the square root, having domain `[0, +infinity]` and codomain `[0, +in
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -538,7 +538,7 @@ Calculates the difference for each element `x1_i` of the input array `x1` with t
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input arrays (i.e., must have a shape to which the input arrays can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input arrays (i.e., must have a shape to which the input arrays can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -563,7 +563,7 @@ Calculates an implementation-dependent approximation to the tangent, having doma
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -589,7 +589,7 @@ Calculates an implementation-dependent approximation to the hyperbolic tangent,
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -611,7 +611,7 @@ Rounds each element `x_i` of the input array `x` to the integer-valued number th
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If specified as a tuple, the tuple must consist of a single entry: the output array. If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 

From d1bb2ba7eb807d838d682599ca9a579feb8f63af Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Fri, 7 Aug 2020 14:05:49 -0700
Subject: [PATCH 50/67] Update conventions

---
 spec/API_specification/elementwise_functions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index ec3b72b4d..81dcff51c 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -6,7 +6,7 @@ A conforming implementation of the array API standard must provide and support t
 
 -   Positional parameters must be [positional-only](https://www.python.org/dev/peps/pep-0570/) parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order.
 -   Optional parameters must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments.
--   For functions returning a single output array, the `out` keyword argument may be either `None`, an array, or a tuple consisting of a single array as its only entry.
+-   For functions returning a single output array, the `out` keyword argument may be either `None`or an array.
 -   When a function returns multiple output arrays, the `out` keyword argument must be a tuple with one entry (either `None` or an array) per output. Providing a single output array when a function returns multiple output arrays must **not** be permitted.
 -   If `out` is not provided or is `None` (the default), an uninitialized return array must be created for each output for which an output array has not been provided.
 -   Broadcasting semantics must follow the semantics defined in this specification.

From d9adebcf82f79e54f2b7b6c9ed13c7722daa7c05 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Fri, 7 Aug 2020 14:39:56 -0700
Subject: [PATCH 51/67] Link to broadcasting document

---
 spec/API_specification/broadcasting.md        |  2 +
 .../elementwise_functions.md                  | 48 +++++++++----------
 spec/purpose_and_scope.md                     |  2 +-
 3 files changed, 27 insertions(+), 25 deletions(-)

diff --git a/spec/API_specification/broadcasting.md b/spec/API_specification/broadcasting.md
index 6364f0ba4..44a50f4b8 100644
--- a/spec/API_specification/broadcasting.md
+++ b/spec/API_specification/broadcasting.md
@@ -1,3 +1,5 @@
+.. _broadcasting:
+
 # Broadcasting
 
 > Array API specification for broadcasting semantics.
diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index 81dcff51c..809a526a0 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -30,7 +30,7 @@ Calculates the absolute value for each element `x_i` of the input array `x` (i.e
 
 -   **out**: _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -55,7 +55,7 @@ Calculates an implementation-dependent approximation of the principal value of t
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -80,7 +80,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic c
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -106,7 +106,7 @@ Calculates the sum for each element `x1_i` of the input array `x1` with the resp
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input arrays (i.e., must have a shape to which the input arrays can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input arrays (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -132,7 +132,7 @@ Calculates an implementation-dependent approximation of the principal value of t
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -158,7 +158,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic s
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -184,7 +184,7 @@ Calculates an implementation-dependent approximation of the principal value of t
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -212,7 +212,7 @@ Calculates an implementation-dependent approximation to the inverse hyperbolic t
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -234,7 +234,7 @@ Rounds each element `x_i` of the input array `x` to the smallest (i.e., closest
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -260,7 +260,7 @@ Calculates an implementation-dependent approximation to the cosine, having domai
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -286,7 +286,7 @@ Calculates an implementation-dependent approximation to the hyperbolic cosine, h
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -312,7 +312,7 @@ Calculates the division for each element `x1_i` of the input array `x1` with the
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input arrays (i.e., must have a shape to which the input arrays can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input arrays (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -338,7 +338,7 @@ Calculates an implementation-dependent approximation to the exponential function
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -360,7 +360,7 @@ Rounds each element `x_i` of the input array `x` to the greatest (i.e., closest
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -386,7 +386,7 @@ Calculates an implementation-dependent approximation to the natural (base `e`) l
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -412,7 +412,7 @@ Calculates the product for each element `x1_i` of the input array `x1` with the
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input arrays (i.e., must have a shape to which the input arrays can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input arrays (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -435,7 +435,7 @@ Rounds each element `x_i` of the input array `x` to the nearest integer-valued n
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -460,7 +460,7 @@ Calculates an implementation-dependent approximation to the sine, having domain
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -486,7 +486,7 @@ Calculates an implementation-dependent approximation to the hyperbolic sine, hav
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -512,7 +512,7 @@ Calculates the square root, having domain `[0, +infinity]` and codomain `[0, +in
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -538,7 +538,7 @@ Calculates the difference for each element `x1_i` of the input array `x1` with t
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input arrays (i.e., must have a shape to which the input arrays can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input arrays (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -563,7 +563,7 @@ Calculates an implementation-dependent approximation to the tangent, having doma
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -589,7 +589,7 @@ Calculates an implementation-dependent approximation to the hyperbolic tangent,
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
@@ -611,7 +611,7 @@ Rounds each element `x_i` of the input array `x` to the integer-valued number th
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
-    -   output array. If provided, the output array must be compatible with the provided input array (i.e., must have a shape to which the input array can broadcast). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
+    -   output array. If provided, the output array must be compatible with the provided input array (see :ref:`broadcasting`). If not provided or is `None`, an uninitialized return array must be created and then filled with the result of each element-wise computation. Default: `None`.
 
 #### Returns
 
diff --git a/spec/purpose_and_scope.md b/spec/purpose_and_scope.md
index fcfab69db..5a73140f2 100644
--- a/spec/purpose_and_scope.md
+++ b/spec/purpose_and_scope.md
@@ -44,7 +44,7 @@ A conforming implementation of the array API standard may provide additional val
 
 For the purposes of this specification, the following terms and definitions apply.
 
-<!-- NOTE: please keep the terms in alphabetical order -->
+<!-- NOTE: please keep terms in alphabetical order -->
 
 ### array
 

From 16a0727b3e973233a6ea93e3eb61cc9ef1f6b634 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Fri, 7 Aug 2020 14:46:52 -0700
Subject: [PATCH 52/67] Add reference

---
 spec/API_specification/elementwise_functions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index 809a526a0..68753dae4 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -9,7 +9,7 @@ A conforming implementation of the array API standard must provide and support t
 -   For functions returning a single output array, the `out` keyword argument may be either `None`or an array.
 -   When a function returns multiple output arrays, the `out` keyword argument must be a tuple with one entry (either `None` or an array) per output. Providing a single output array when a function returns multiple output arrays must **not** be permitted.
 -   If `out` is not provided or is `None` (the default), an uninitialized return array must be created for each output for which an output array has not been provided.
--   Broadcasting semantics must follow the semantics defined in this specification.
+-   Broadcasting semantics must follow the semantics defined in this specification (see :ref:`broadcasting`).
 -   Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.
 
 <!-- NOTE: please keep the functions in alphabetical order -->

From 2e3a597dd440056d58aee4caa59392d28675a923 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Fri, 7 Aug 2020 15:10:07 -0700
Subject: [PATCH 53/67] Add document specifying the behavior of the `out`
 keyword argument

---
 spec/API_specification/out_keyword.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)
 create mode 100644 spec/API_specification/out_keyword.md

diff --git a/spec/API_specification/out_keyword.md b/spec/API_specification/out_keyword.md
new file mode 100644
index 000000000..f253089f8
--- /dev/null
+++ b/spec/API_specification/out_keyword.md
@@ -0,0 +1,12 @@
+.. _out-keyword:
+
+# out
+
+> Array API specification for the `out` keyword argument.
+
+A conforming implementation of the array API standard must adhere to the following conventions.
+
+-   Functions and methods which support providing one or more output arrays must do so via a single `out` keyword argument whose default value is `None`.
+-   If a function or method returns a single output array, the `out` keyword argument may be either `None` or an array.
+-   If a function or method returns multiple output arrays, the `out` keyword argument must be a tuple with one entry (either `None` or an array) per output. Providing a single output array when a function or method returns multiple output arrays is **not** permitted.
+-   If `out` is not provided or is `None`, an uninitialized return array must be created for each output for which an output array has not been provided.
\ No newline at end of file

From a2da7d9a6f9a0e56d1fc52be3a896fbbe2703373 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Fri, 7 Aug 2020 15:43:05 -0700
Subject: [PATCH 54/67] Update conventions

---
 spec/API_specification/elementwise_functions.md | 6 ++----
 spec/API_specification/index.rst                | 5 +++--
 2 files changed, 5 insertions(+), 6 deletions(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index 68753dae4..80ac474db 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -6,10 +6,8 @@ A conforming implementation of the array API standard must provide and support t
 
 -   Positional parameters must be [positional-only](https://www.python.org/dev/peps/pep-0570/) parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order.
 -   Optional parameters must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments.
--   For functions returning a single output array, the `out` keyword argument may be either `None`or an array.
--   When a function returns multiple output arrays, the `out` keyword argument must be a tuple with one entry (either `None` or an array) per output. Providing a single output array when a function returns multiple output arrays must **not** be permitted.
--   If `out` is not provided or is `None` (the default), an uninitialized return array must be created for each output for which an output array has not been provided.
--   Broadcasting semantics must follow the semantics defined in this specification (see :ref:`broadcasting`).
+-   The `out` keyword argument must follow the conventions defined in :ref:`out_keyword`.
+-   Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`.
 -   Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.
 
 <!-- NOTE: please keep the functions in alphabetical order -->
diff --git a/spec/API_specification/index.rst b/spec/API_specification/index.rst
index 23306276e..e364ddcdc 100644
--- a/spec/API_specification/index.rst
+++ b/spec/API_specification/index.rst
@@ -6,7 +6,8 @@ API specification
    :maxdepth: 1
 
    array_object
-   elementwise_functions
    indexing
-   broadcasting
    casting
+   broadcasting
+   out_keyword
+   elementwise_functions

From 076a6d5dd3967a62adb9c2bfffb110cc1c16b5d6 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Fri, 7 Aug 2020 15:50:30 -0700
Subject: [PATCH 55/67] Add references

---
 spec/API_specification/elementwise_functions.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index 80ac474db..adbb76ac7 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -100,7 +100,7 @@ Calculates the sum for each element `x1_i` of the input array `x1` with the resp
 
 -   **x2**: _&lt;array&gt;_
 
-    -   second input array. Must be compatible with `x1` (i.e., `x1` and `x2` must be able to broadcast to a common shape). 
+    -   second input array. Must be compatible with `x1` (i.e., `x1` and `x2` must be able to broadcast to a common shape; see :ref:`broadcasting`). 
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
@@ -306,7 +306,7 @@ Calculates the division for each element `x1_i` of the input array `x1` with the
 
 -   **x2**: _&lt;array&gt;_
 
-    -   divisor input array. Must be compatible with `x1` (i.e., `x1` and `x2` must be able to broadcast to a common shape).
+    -   divisor input array. Must be compatible with `x1` (i.e., `x1` and `x2` must be able to broadcast to a common shape; see :ref:`broadcasting`).
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
@@ -406,7 +406,7 @@ Calculates the product for each element `x1_i` of the input array `x1` with the
 
 -   **x2**: _&lt;array&gt;_
 
-    -   second input array. Must be compatible with `x1` (i.e., `x1` and `x2` must be able to broadcast to a common shape).
+    -   second input array. Must be compatible with `x1` (i.e., `x1` and `x2` must be able to broadcast to a common shape; see :ref:`broadcasting`).
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
@@ -532,7 +532,7 @@ Calculates the difference for each element `x1_i` of the input array `x1` with t
 
 -   **x2**: _&lt;array&gt;_
 
-    -   second input array. Must be compatible with `x1` (i.e., `x1` and `x2` must be able to broadcast to a common shape).
+    -   second input array. Must be compatible with `x1` (i.e., `x1` and `x2` must be able to broadcast to a common shape; see :ref:`broadcasting`).
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 

From be2a6367ffe845c48d05efe93b15b22f9e3ff56f Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Fri, 7 Aug 2020 16:30:39 -0700
Subject: [PATCH 56/67] Add explainer for arrays of unequal rank

---
 spec/API_specification/broadcasting.md | 2 ++
 spec/purpose_and_scope.md              | 8 ++++++++
 2 files changed, 10 insertions(+)

diff --git a/spec/API_specification/broadcasting.md b/spec/API_specification/broadcasting.md
index 44a50f4b8..0c63155f2 100644
--- a/spec/API_specification/broadcasting.md
+++ b/spec/API_specification/broadcasting.md
@@ -14,6 +14,8 @@ Broadcasting facilitates user ergonomics by encouraging users to avoid unnecessa
 
 Given an element-wise operation involving two compatible arrays, an array having a singleton dimension (i.e., a dimension whose size is one) is broadcast (i.e., virtually repeated) across an array having a corresponding non-singleton dimension.
 
+If two arrays are of unequal rank, the array having a lower rank is promoted to a higher rank by (virtually) prepending singleton dimensions until the number of dimensions matches that of the array having a higher rank.
+
 The results of the element-wise operation must be stored in an array having a shape determined by the following algorithm.
 
 1.  Let `A` and `B` both be arrays.
diff --git a/spec/purpose_and_scope.md b/spec/purpose_and_scope.md
index 5a73140f2..678fee331 100644
--- a/spec/purpose_and_scope.md
+++ b/spec/purpose_and_scope.md
@@ -62,10 +62,18 @@ two arrays whose dimensions are compatible (i.e., where the size of each dimensi
 
 an operation performed element-by-element, in which individual array elements are considered in isolation and independently of other elements within the same array.
 
+### rank
+
+number of array dimensions (not to be confused with the number of linearly independent columns of a matrix).
+
 ### shape
 
 a tuple of `N` non-negative integers that specify the sizes of each dimension and where `N` corresponds to the number of dimensions.
 
+### singleton dimension
+
+a dimension whose size is one.
+
 * * *
 
 ## Normative References

From bbeae1f5330da3437c15edf868e1c5de5c87543d Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Fri, 7 Aug 2020 16:32:38 -0700
Subject: [PATCH 57/67] Fix reference

---
 spec/API_specification/elementwise_functions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index adbb76ac7..eb3619dcb 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -6,7 +6,7 @@ A conforming implementation of the array API standard must provide and support t
 
 -   Positional parameters must be [positional-only](https://www.python.org/dev/peps/pep-0570/) parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order.
 -   Optional parameters must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments.
--   The `out` keyword argument must follow the conventions defined in :ref:`out_keyword`.
+-   The `out` keyword argument must follow the conventions defined in :ref:`out-keyword`.
 -   Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`.
 -   Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.
 

From 6d06f13987599d1b933d8638a86239bc7440e914 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Fri, 7 Aug 2020 16:33:22 -0700
Subject: [PATCH 58/67] Update comment

---
 spec/API_specification/broadcasting.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/API_specification/broadcasting.md b/spec/API_specification/broadcasting.md
index 0c63155f2..53a36a103 100644
--- a/spec/API_specification/broadcasting.md
+++ b/spec/API_specification/broadcasting.md
@@ -104,7 +104,7 @@ A      (2d array):      2 x 1
 B      (3d array):  8 x 4 x 3   # second dimension does not match
 
 A      (3d array):  15 x 3 x 5
-B      (2d array):  15 x 3      # size-1 dimensions can only be prepended, not appended
+B      (2d array):  15 x 3      # singleton dimensions can only be prepended, not appended
 ```
 
 ## In-place Semantics

From 22ee3b0d1e2d586c58b50d319a7126b55e449052 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Fri, 7 Aug 2020 16:40:15 -0700
Subject: [PATCH 59/67] Add link to Python documentation for reading type
 annotations

---
 spec/purpose_and_scope.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/purpose_and_scope.md b/spec/purpose_and_scope.md
index 678fee331..0d081e87a 100644
--- a/spec/purpose_and_scope.md
+++ b/spec/purpose_and_scope.md
@@ -24,7 +24,7 @@
 
 ## How to read this document
 
-
+For guidance on how to read and understand the type annotations included in this specification, consult the Python [documentation](https://docs.python.org/3/library/typing.html).
 
 
 ## How to adopt this API

From 78186875abe5d797989e848bbedcae4a51f0a5be Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Fri, 7 Aug 2020 17:23:11 -0700
Subject: [PATCH 60/67] Add convention regarding shape immutatibility for
 output arrays

---
 spec/API_specification/out_keyword.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/spec/API_specification/out_keyword.md b/spec/API_specification/out_keyword.md
index f253089f8..36937b388 100644
--- a/spec/API_specification/out_keyword.md
+++ b/spec/API_specification/out_keyword.md
@@ -7,6 +7,7 @@
 A conforming implementation of the array API standard must adhere to the following conventions.
 
 -   Functions and methods which support providing one or more output arrays must do so via a single `out` keyword argument whose default value is `None`.
--   If a function or method returns a single output array, the `out` keyword argument may be either `None` or an array.
+-   If a function or method returns a single output array, the `out` keyword argument must be either `None` or an array.
 -   If a function or method returns multiple output arrays, the `out` keyword argument must be a tuple with one entry (either `None` or an array) per output. Providing a single output array when a function or method returns multiple output arrays is **not** permitted.
--   If `out` is not provided or is `None`, an uninitialized return array must be created for each output for which an output array has not been provided.
\ No newline at end of file
+-   If `out` is not provided or is `None`, an uninitialized return array must be created for each output for which an output array has not been provided.
+-   Functions and methods which support the `out` keyword argument are **not** permitted to change the shape of provided output arrays.
\ No newline at end of file

From e2ee01bcb83f0339cacbfe1a4f326103336378d1 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Fri, 7 Aug 2020 17:26:14 -0700
Subject: [PATCH 61/67] Update descriptions

---
 spec/API_specification/elementwise_functions.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index eb3619dcb..9b6f38c9a 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -100,7 +100,7 @@ Calculates the sum for each element `x1_i` of the input array `x1` with the resp
 
 -   **x2**: _&lt;array&gt;_
 
-    -   second input array. Must be compatible with `x1` (i.e., `x1` and `x2` must be able to broadcast to a common shape; see :ref:`broadcasting`). 
+    -   second input array. Must be compatible with `x1` (see :ref:`broadcasting`). 
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
@@ -306,7 +306,7 @@ Calculates the division for each element `x1_i` of the input array `x1` with the
 
 -   **x2**: _&lt;array&gt;_
 
-    -   divisor input array. Must be compatible with `x1` (i.e., `x1` and `x2` must be able to broadcast to a common shape; see :ref:`broadcasting`).
+    -   divisor input array. Must be compatible with `x1` (see :ref:`broadcasting`).
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
@@ -406,7 +406,7 @@ Calculates the product for each element `x1_i` of the input array `x1` with the
 
 -   **x2**: _&lt;array&gt;_
 
-    -   second input array. Must be compatible with `x1` (i.e., `x1` and `x2` must be able to broadcast to a common shape; see :ref:`broadcasting`).
+    -   second input array. Must be compatible with `x1` (see :ref:`broadcasting`).
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 
@@ -532,7 +532,7 @@ Calculates the difference for each element `x1_i` of the input array `x1` with t
 
 -   **x2**: _&lt;array&gt;_
 
-    -   second input array. Must be compatible with `x1` (i.e., `x1` and `x2` must be able to broadcast to a common shape; see :ref:`broadcasting`).
+    -   second input array. Must be compatible with `x1` (see :ref:`broadcasting`).
 
 -   **out**:  _Optional\[ &lt;array&gt; ]_
 

From 6f1274b62e7e72eab0ad9f20c7bcd716ed7ed0e8 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Fri, 7 Aug 2020 17:57:44 -0700
Subject: [PATCH 62/67] Add data types document

---
 spec/API_specification/data_types.md          | 53 +++++++++++++++++++
 .../elementwise_functions.md                  |  1 +
 spec/purpose_and_scope.md                     |  4 +-
 3 files changed, 56 insertions(+), 2 deletions(-)
 create mode 100644 spec/API_specification/data_types.md

diff --git a/spec/API_specification/data_types.md b/spec/API_specification/data_types.md
new file mode 100644
index 000000000..1557a5d87
--- /dev/null
+++ b/spec/API_specification/data_types.md
@@ -0,0 +1,53 @@
+.. _data-types:
+
+# Data Types
+
+> Array API specification for supported data types.
+
+A conforming implementation of the array API standard must provide and support the following data types.
+
+A conforming implementation of the array API standard may provide and support additional data types beyond those described in this specification.
+
+## bool
+
+Boolean (`True` or `False`) stored as a byte.
+
+## int8
+
+An 8-bit signed integer whose values exist on the interval `[-128, +127]`.
+
+## int16
+
+A 16-bit signed integer whose values exist on the interval `[−32,767, +32,767]`.
+
+## int32
+
+A 32-bit signed integer whose values exist on the interval `[−2,147,483,647, +2,147,483,647]`.
+
+## int64
+
+A 64-bit signed integer whose values exist on the interval `[−9,223,372,036,854,775,807, +9,223,372,036,854,775,807]`.
+
+## uint8
+
+An 8-bit unsigned integer whose values exist on the interval `[0, +255]`.
+
+## uint16
+
+A 16-bit unsigned integer whose values exist on the interval `[0, +65,535]`.
+
+## uint32
+
+A 32-bit unsigned integer whose values exist on the interval `[0, +4,294,967,295]`.
+
+## uint64
+
+A 64-bit unsigned integer whose values exist on the interval `[0, +18,446,744,073,709,551,615]`.
+
+## float32
+
+IEEE 754 single-precision binary floating-point number (see IEEE 754-2019).
+
+## float64
+
+IEEE 754 double-precision binary floating-point number (see IEEE 754-2019).
\ No newline at end of file
diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index 9b6f38c9a..f847ef497 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -8,6 +8,7 @@ A conforming implementation of the array API standard must provide and support t
 -   Optional parameters must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments.
 -   The `out` keyword argument must follow the conventions defined in :ref:`out-keyword`.
 -   Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`.
+-   Unless stated otherwise, functions must support the data types defined in :ref:`data-types`.
 -   Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.
 
 <!-- NOTE: please keep the functions in alphabetical order -->
diff --git a/spec/purpose_and_scope.md b/spec/purpose_and_scope.md
index 0d081e87a..9481d72d1 100644
--- a/spec/purpose_and_scope.md
+++ b/spec/purpose_and_scope.md
@@ -34,9 +34,9 @@ For guidance on how to read and understand the type annotations included in this
 
 ## Conformance
 
-A conforming implementation of the array API standard must provide and support all the functions, arguments, syntax, and semantics described in this specification.
+A conforming implementation of the array API standard must provide and support all the functions, arguments, data types, syntax, and semantics described in this specification.
 
-A conforming implementation of the array API standard may provide additional values, objects, properties, and functions beyond those described in this specification.
+A conforming implementation of the array API standard may provide additional values, objects, properties, data types, and functions beyond those described in this specification.
 
 * * *
 

From ca6e87e1d1b81c7c57fe231756f1f207aff86082 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Fri, 7 Aug 2020 18:00:05 -0700
Subject: [PATCH 63/67] Update index

---
 spec/API_specification/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/spec/API_specification/index.rst b/spec/API_specification/index.rst
index e364ddcdc..72a6e605d 100644
--- a/spec/API_specification/index.rst
+++ b/spec/API_specification/index.rst
@@ -7,6 +7,7 @@ API specification
 
    array_object
    indexing
+   data_types
    casting
    broadcasting
    out_keyword

From 9ddb80adf589728e041589d4ef3cbd8780b960ba Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Fri, 7 Aug 2020 18:03:47 -0700
Subject: [PATCH 64/67] Update descriptions

---
 spec/API_specification/data_types.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/spec/API_specification/data_types.md b/spec/API_specification/data_types.md
index 1557a5d87..3380d7782 100644
--- a/spec/API_specification/data_types.md
+++ b/spec/API_specification/data_types.md
@@ -46,8 +46,8 @@ A 64-bit unsigned integer whose values exist on the interval `[0, +18,446,744,07
 
 ## float32
 
-IEEE 754 single-precision binary floating-point number (see IEEE 754-2019).
+IEEE 754 single-precision (32-bit) binary floating-point number (see IEEE 754-2019).
 
 ## float64
 
-IEEE 754 double-precision binary floating-point number (see IEEE 754-2019).
\ No newline at end of file
+IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-2019).
\ No newline at end of file

From 0e272d927f50dde426c403fde6181f80a6850950 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Fri, 7 Aug 2020 18:21:32 -0700
Subject: [PATCH 65/67] Add type promotion rules

---
 .../elementwise_functions.md                  |  1 +
 spec/API_specification/type_promotion.md      | 70 +++++++++++++++++++
 2 files changed, 71 insertions(+)
 create mode 100644 spec/API_specification/type_promotion.md

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index f847ef497..71c2bcfff 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -9,6 +9,7 @@ A conforming implementation of the array API standard must provide and support t
 -   The `out` keyword argument must follow the conventions defined in :ref:`out-keyword`.
 -   Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`.
 -   Unless stated otherwise, functions must support the data types defined in :ref:`data-types`.
+-   Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type_promotion`.
 -   Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.
 
 <!-- NOTE: please keep the functions in alphabetical order -->
diff --git a/spec/API_specification/type_promotion.md b/spec/API_specification/type_promotion.md
new file mode 100644
index 000000000..4d6980597
--- /dev/null
+++ b/spec/API_specification/type_promotion.md
@@ -0,0 +1,70 @@
+.. _type-promotion:
+
+# Type Promotion Rules
+
+> Array API specification for type promotion rules.
+
+A conforming implementation of the array API standard must implement the following type promotion rules governing the common result type for two **array** operands during an arithmetic operation.
+
+A conforming implementation of the array API standard may support additional type promotion rules beyond those described in this specification.
+
+## Rules
+
+<!-- Note: please keep table columns aligned -->
+
+-   signed integer type promotion table:
+
+    |        | i1 | i2 | i4 | i8 |
+    | ------ | -- | -- | -- | -- |
+    | **i1** | i1 | i2 | i4 | i8 |
+    | **i2** | i2 | i2 | i4 | i8 |
+    | **i4** | i4 | i4 | i4 | i8 |
+    | **i8** | i8 | i8 | i8 | i8 |
+
+    where
+
+    -   **i1**: 8-bit signed integer
+    -   **i2**: 16-bit signed integer
+    -   **i4**: 32-bit signed integer
+    -   **i8**: 64-bit signed integer
+
+-   unsigned integer type promotion table:
+
+    |        | u1 | u2 | u4 | u8 |
+    | ------ | -- | -- | -- | -- |
+    | **u1** | u1 | u2 | u4 | u8 |
+    | **u2** | u2 | u2 | u4 | u8 |
+    | **u4** | u4 | u4 | u4 | u8 |
+    | **u8** | u8 | u8 | u8 | u8 |
+
+    where
+
+    -   **u1**: 8-bit unsigned integer
+    -   **u2**: 16-bit unsigned integer
+    -   **u4**: 32-bit unsigned integer
+    -   **u8**: 64-bit unsigned integer
+
+-   mixed unsigned and signed integer type promotion table:
+
+    |        | u1 | u2 | u4 |
+    | ------ | -- | -- | -- |
+    | **i1** | i2 | i4 | i8 |
+    | **i2** | i2 | i4 | i8 |
+    | **i4** | i4 | i4 | i8 |
+
+-   floating-point type promotion table:
+
+    |        | f4 | f8 |
+    | ------ | -- | -- |
+    | **f4** | f4 | f8 |
+    | **f8** | f8 | f8 |
+
+    where
+
+    -   **f4**: single-precision (32-bit) floating-point number
+    -   **f8**: double-precision (64-bit) floating-point number
+
+## Notes
+
+-   Type promotion rules **strictly** apply when determining the common result type for two **array** operands during an arithmetic operation, regardless of array dimension. Accordingly, zero-dimensional arrays are subject to the same type promotion rules as dimensional arrays.
+-   Non-array ("scalar") operands are **not** permitted to participate in type promotion.
\ No newline at end of file

From f1f8490f715cf0401da37f046a5c2c4d87cb35f5 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Fri, 7 Aug 2020 18:22:01 -0700
Subject: [PATCH 66/67] Update index

---
 spec/API_specification/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/spec/API_specification/index.rst b/spec/API_specification/index.rst
index 72a6e605d..c256627b6 100644
--- a/spec/API_specification/index.rst
+++ b/spec/API_specification/index.rst
@@ -8,6 +8,7 @@ API specification
    array_object
    indexing
    data_types
+   type_promotion
    casting
    broadcasting
    out_keyword

From 38db14994e938f27efd59914d63d4960f17347b2 Mon Sep 17 00:00:00 2001
From: Athan Reines <kgryte@gmail.com>
Date: Fri, 7 Aug 2020 18:30:04 -0700
Subject: [PATCH 67/67] Fix reference

---
 spec/API_specification/elementwise_functions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/API_specification/elementwise_functions.md b/spec/API_specification/elementwise_functions.md
index 71c2bcfff..2569a0f6e 100644
--- a/spec/API_specification/elementwise_functions.md
+++ b/spec/API_specification/elementwise_functions.md
@@ -9,7 +9,7 @@ A conforming implementation of the array API standard must provide and support t
 -   The `out` keyword argument must follow the conventions defined in :ref:`out-keyword`.
 -   Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`.
 -   Unless stated otherwise, functions must support the data types defined in :ref:`data-types`.
--   Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type_promotion`.
+-   Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`.
 -   Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.
 
 <!-- NOTE: please keep the functions in alphabetical order -->