Add notes to dtype sections to make sections easier to understand

spec/API_specification/data_types.md

@@ -8,6 +8,16 @@ A conforming implementation of the array API standard must provide and support t
 
 A conforming implementation of the array API standard may provide and support additional data types beyond those described in this specification.
 
+.. note::
+
+    These dtypes are objects that can be used as dtype specifiers in functions and methods (e.g., `zeros((2, 3), dtype=float32)`). A conforming implementation may add methods or attributes to dtype objects; these are not part of this specification however.
+
+.. note::
+
+    Implementations may provide others ways to specify dtypes (e.g.,
+    `zeros((2, 3), dtype='f4')`); these are not part of this specification however.
+
+
 ## bool
 
 Boolean (`True` or `False`) stored as a byte.

spec/API_specification/type_promotion.md

@@ -8,6 +8,11 @@ A conforming implementation of the array API standard must implement the followi
 
 A conforming implementation of the array API standard may support additional type promotion rules beyond those described in this specification.
 
+.. note::
+
+    Type codes are used here to keep tables readable, they are not part of the standard.
+    In code, use the dtype objects specified in :ref:`data-types` (e.g., `int16` rather than `'i2'`).
+
 ## Rules
 
 <!-- Note: please keep table columns aligned -->
@@ -23,10 +28,10 @@ A conforming implementation of the array API standard may support additional typ
 
     where
 
-    -   **i1**: 8-bit signed integer
-    -   **i2**: 16-bit signed integer
-    -   **i4**: 32-bit signed integer
-    -   **i8**: 64-bit signed integer
+    -   **i1**: 8-bit signed integer (i.e., `int8`)
+    -   **i2**: 16-bit signed integer (i.e., `int16`)
+    -   **i4**: 32-bit signed integer (i.e., `int32`)
+    -   **i8**: 64-bit signed integer (i.e., `int64`)
 
 -   unsigned integer type promotion table:
 
@@ -39,10 +44,10 @@ A conforming implementation of the array API standard may support additional typ
 
     where
 
-    -   **u1**: 8-bit unsigned integer
-    -   **u2**: 16-bit unsigned integer
-    -   **u4**: 32-bit unsigned integer
-    -   **u8**: 64-bit unsigned integer
+    -   **u1**: 8-bit unsigned integer (i.e., `uint8`)
+    -   **u2**: 16-bit unsigned integer (i.e., `uint16`)
+    -   **u4**: 32-bit unsigned integer (i.e., `uint32`)
+    -   **u8**: 64-bit unsigned integer (i.e., `uint64`)
 
 -   mixed unsigned and signed integer type promotion table:
 
@@ -61,10 +66,16 @@ A conforming implementation of the array API standard may support additional typ
 
     where
 
-    -   **f4**: single-precision (32-bit) floating-point number
-    -   **f8**: double-precision (64-bit) floating-point number
+    -   **f4**: single-precision (32-bit) floating-point number (i.e., `float32`)
+    -   **f8**: double-precision (64-bit) floating-point number (i.e., `float64`)
 
 ## 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.
+-   Non-array ("scalar") operands are **not** permitted to participate in type promotion.
+
+
+.. note::
+
+    Mixed integer and floating-point type promotion rules are not specified
+    because behaviour varies between implementations.