Clean up duplicate blurbs on function conventions; improve fft description

spec/API_specification/array_object.rst

@@ -5,14 +5,7 @@ Array object
 
     Array API specification for array object attributes and methods.
 
-A conforming implementation of the array API standard must provide and support an array object having the following attributes and methods 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 method 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.
-*   Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`.
-*   Unless stated otherwise, methods must support the data types defined in :ref:`data-types`.
-*   Unless stated otherwise, methods must adhere to the type promotion rules defined in :ref:`type-promotion`.
-*   Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.
+A conforming implementation of the array API standard must provide and support an array object having the following attributes and methods.
 
 Furthermore, a conforming implementation of the array API standard must support array objects of arbitrary rank ``N`` (i.e., number of dimensions), where ``N`` is greater than or equal to zero.
 

spec/API_specification/creation_functions.rst

@@ -3,10 +3,8 @@ Creation Functions
 
     Array API specification for creating arrays.
 
-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.
 
--   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.
 
 Objects in API
 --------------

spec/API_specification/elementwise_functions.rst

@@ -5,17 +5,6 @@ Element-wise Functions
 
     Array API specification for element-wise 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.
--   Optional parameters must be `keyword-only <https://www.python.org/dev/peps/pep-3102/>`_ arguments.
--   Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`.
--   Unless stated otherwise, functions must support the data types defined in :ref:`data-types`.
--   Functions may only be required for a subset of input data type. Libraries may choose to implement functions for additional data types, but that behavior is not required by the specification. See :ref:`data-type-categories`.
--   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.
--   Unless stated otherwise, element-wise mathematical functions must satisfy the minimum accuracy requirements defined in :ref:`accuracy`.
-
 Objects in API
 --------------
 

spec/API_specification/index.rst

@@ -3,6 +3,18 @@
 API specification
 =================
 
+A conforming implementation of the array API standard must provide and support the APIs and behavior detailed in this specification while adhering to the following conventions.
+
+-   When a function signature includes a `/`, positional parameters must be `positional-only <https://www.python.org/dev/peps/pep-0570/>`_ parameters. See :ref:`function-and-method-signatures`.
+-   When a function signature includes a `*`, optional parameters must be `keyword-only <https://www.python.org/dev/peps/pep-3102/>`_ arguments. See :ref:`function-and-method-signatures`.
+-   Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`.
+-   Unless stated otherwise, functions must support the data types defined in :ref:`data-types`.
+-   Functions may only be required for a subset of input data types. Libraries may choose to implement functions for additional data types, but that behavior is not required by the specification. See :ref:`data-type-categories`.
+-   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.
+-   Unless stated otherwise, element-wise mathematical functions must satisfy the minimum accuracy requirements defined in :ref:`accuracy`.
+
+
 .. toctree::
    :caption: API specification
    :maxdepth: 3

spec/API_specification/indexing_functions.rst

@@ -5,13 +5,8 @@ Indexing Functions
 
     Array API specification for functions for indexing arrays.
 
-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.
 
--   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.
--   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`.
 
 Objects in API
 --------------

spec/API_specification/linear_algebra_functions.rst

@@ -3,14 +3,8 @@ Linear Algebra Functions
 
   Array API specification for linear algebra 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.
 
-* 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.
-* 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.
 
 .. currentmodule:: array_api
 

spec/API_specification/manipulation_functions.rst

@@ -3,11 +3,8 @@ Manipulation Functions
 
     Array API specification for manipulating arrays.
 
-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.
 
--   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.
--   Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`.
 
 Objects in API
 --------------

spec/API_specification/searching_functions.rst

@@ -5,13 +5,8 @@ Searching Functions
 
     Array API specification for functions for searching arrays.
 
-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.
 
--   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.
--   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`.
 
 Objects in API
 --------------

spec/API_specification/set_functions.rst

@@ -3,11 +3,8 @@ Set Functions
 
     Array API specification for creating and operating on sets.
 
-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.
 
--   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.
--   Unless stated otherwise, functions must support the data types defined in :ref:`data-types`.
 
 Objects in API
 --------------

spec/API_specification/sorting_functions.rst

@@ -3,11 +3,8 @@ Sorting Functions
 
   Array API specification for sorting 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.
 
-* 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.
-* Unless stated otherwise, functions must support the data types defined in :ref:`data-types`.
 
 .. note::
 

spec/API_specification/statistical_functions.rst

@@ -3,14 +3,8 @@ Statistical Functions
 
     Array API specification for statistical 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.
--   Optional parameters must be `keyword-only <https://www.python.org/dev/peps/pep-3102/>`_ arguments.
--   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.
+A conforming implementation of the array API standard must provide and support the following functions.
+
 
 Objects in API
 --------------

spec/API_specification/utility_functions.rst

@@ -3,14 +3,8 @@ Utility Functions
 
     Array API specification for utility 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.
--   Optional parameters must be `keyword-only <https://www.python.org/dev/peps/pep-3102/>`_ arguments.
--   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.
+A conforming implementation of the array API standard must provide and support the following functions.
+
 
 Objects in API
 --------------

spec/extensions/fourier_transform_functions.rst

@@ -3,18 +3,23 @@ Fourier transform Functions
 
     Array API specification for Fourier transform functions.
 
-A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions.
+Extension name and usage
+------------------------
+
+The name of the namespace providing the extension must be: ``fft``.
+
+If implemented, this ``fft`` extension must be retrievable via::
+
+    >>> xp = x.__array_namespace__()
+    >>> if hasattr(xp, 'fft'):
+    >>>    # Use `xp.fft`
 
--   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.
--   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.
 
 Objects in API
 --------------
 
+A conforming implementation of this ``fft`` extension must provide and support the following functions.
+
 .. currentmodule:: array_api.fft
 
 ..

spec/extensions/index.rst

@@ -21,6 +21,9 @@ The mechanism through which the extension namespace is made available is up to
 the implementer, e.g. via a regular submodule that is imported under the
 ``linalg`` name, or via a module-level ``__getattr__``.
 
+The functions in an extension must adhere to the same conventions as those in
+the array API standard. See :ref:`api-specification`.
+
 
 Extensions
 ----------

spec/extensions/linear_algebra_functions.rst

@@ -17,20 +17,6 @@ If implemented, this ``linalg`` extension must be retrievable via::
     >>>    # Use `xp.linalg`
 
 
-General syntax and semantics rules
-----------------------------------
-
-.. TODO: get rid of this here, it's duplicated over and over
-
-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.
--   Optional parameters must be `keyword-only <https://www.python.org/dev/peps/pep-3102/>`_ arguments.
--   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.
-
 Design Principles
 -----------------
 
@@ -95,6 +81,9 @@ Accordingly, the standardization process affords the opportunity to reduce inter
 
 Objects in API
 --------------
+
+A conforming implementation of this ``linalg`` extension must provide and support the following functions.
+
 ..
   NOTE: please keep the functions in alphabetical order