Some improvements to type hints (#230)

* Fix alphabetical function ordering in the linear algebra extension

* Update some type hints in the spec

These come from comments on the NumPy pull request
numpy/numpy#18585.

* Clarify that the where() result type is only based on the last two arguments

* Use Literal[] for the qr() mode argument type hint

* Add bool and int to the asarray type hints

* Fix a typo in the __setitem__ annotations

spec/API_specification/array_object.md

@@ -780,7 +780,7 @@ The `matmul` function must implement the same semantics as the built-in `@` oper
 
 -   **self**: _<array>_
 
-    -   array instance. Should have a numeric data type. Must have at least one dimension. If `self` is one-dimensional having shape `(M)` and `other` has more than one dimension, `self` must be promoted to a two-dimensional array by prepending `1` to its dimensions (i.e., must have shape `(1, M)`). After matrix multiplication, the prepended dimensions in the returned array must be removed. If `self` has more than one dimension (including after vector-to-matrix promotion), `self` must be compatible with `other` (see {ref}`broadcasting`). If `self` has shape `(..., M, K)`, the innermost two dimensions form matrices on which to perform matrix multiplication. 
+    -   array instance. Should have a numeric data type. Must have at least one dimension. If `self` is one-dimensional having shape `(M)` and `other` has more than one dimension, `self` must be promoted to a two-dimensional array by prepending `1` to its dimensions (i.e., must have shape `(1, M)`). After matrix multiplication, the prepended dimensions in the returned array must be removed. If `self` has more than one dimension (including after vector-to-matrix promotion), `self` must be compatible with `other` (see {ref}`broadcasting`). If `self` has shape `(..., M, K)`, the innermost two dimensions form matrices on which to perform matrix multiplication.
 
 -   **other**: _<array>_
 
@@ -809,7 +809,7 @@ The `matmul` function must implement the same semantics as the built-in `@` oper
 
 -   if either `self` or `other` is a zero-dimensional array.
 -   if `self` is a one-dimensional array having shape `(N)`, `other` is a one-dimensional array having shape `(M)`, and `N != M`.
--   if `self` is an array having shape `(..., M, K)`, `other` is an array having shape `(..., L, N)`, and `K != L`. 
+-   if `self` is an array having shape `(..., M, K)`, `other` is an array having shape `(..., L, N)`, and `K != L`.
 
 (method-__mod__)=
 ### \_\_mod\_\_(self, other, /)
@@ -1066,7 +1066,7 @@ Sets `self[key]` to `value`.
 
 #### Parameters
 
--   **self**: _<array;>_
+-   **self**: _<array>_
 
     -   array instance.
 

spec/API_specification/creation_functions.md

@@ -57,7 +57,7 @@ Convert the input to an array.
 
 #### Parameters
 
--   **obj**: _Union\[ float, NestedSequence\[ bool | int | float ], SupportsDLPack, SupportsBufferProtocol ]_
+-   **obj**: _Union\[ <array>, bool, int, float, NestedSequence\[ bool | int | float ], SupportsDLPack, SupportsBufferProtocol ]_
 
     -   Object to be converted to an array. Can be a Python scalar, a (possibly nested) sequence of Python scalars, or an object supporting DLPack or the Python buffer protocol.
 

spec/API_specification/manipulation_functions.md

@@ -19,7 +19,7 @@ Joins a sequence of arrays along an existing axis.
 
 #### Parameters
 
--   **arrays**: _Tuple\[ <array>, ... ]_
+-   **arrays**: _Union\[Tuple\[ <array>, ... ], List\[ <array> ] ]_
 
     -   input arrays to join. The arrays must have the same shape, except in the dimension specified by `axis`.
 
@@ -154,7 +154,7 @@ Joins a sequence of arrays along a new axis.
 
 #### Parameters
 
--   **arrays**: _Tuple\[ <array>, ... ]_
+-   **arrays**: _Union\[Tuple\[ <array>, ... ], List\[ <array> ] ]_
 
     -   input arrays to join. Each array must have the same shape.
 

spec/API_specification/searching_functions.md

@@ -27,7 +27,7 @@ Returns the indices of the maximum values along a specified axis. When the maxim
 
     -   input array.
 
--   **axis**: _int_
+-   **axis**: _Optional\[ int ]_
 
     -   axis along which to search. If `None`, the function must return the index of the maximum value of the flattened array. Default: `None`.
 
@@ -52,7 +52,7 @@ Returns the indices of the minimum values along a specified axis. When the minim
 
     -   input array.
 
--   **axis**: _int_
+-   **axis**: _Optional\[ int ]_
 
     -   axis along which to search. If `None`, the function must return the index of the minimum value of the flattened array. Default: `None`.
 
@@ -112,4 +112,4 @@ Returns elements chosen from `x1` or `x2` depending on `condition`.
 
 -   **out**: _<array>_
 
-    -   an array with elements from `x1` where `condition` is `True`, and elements from `x2` elsewhere. The returned array must have a data type determined by {ref}`type-promotion` rules.
+    -   an array with elements from `x1` where `condition` is `True`, and elements from `x2` elsewhere. The returned array must have a data type determined by {ref}`type-promotion` rules with the arrays `x1` and `x2`.

spec/extensions/linear_algebra_functions.md

@@ -465,7 +465,7 @@ Computes the qr factorization of a matrix (or a stack of matrices), where `q` is
 
     -   input array having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices. Should have a floating-point data type.
 
--   **mode**: _str_
+-   **mode**: _Literal\[ 'reduced', 'complete' ]_
 
     -   factorization mode. Should be one of the following modes:
 
@@ -552,7 +552,7 @@ Computes the singular value decomposition `A = USVh` of a matrix (or a stack of
 
 #### Returns
 
--   **out**: _Union\[ <array>, Tuple\[ <array>, ... ] ]_
+-   **out**: _Tuple\[ <array>, <array>, <array> ]_
 
     -   a namedtuple `(u, s, vh)` whose
 
@@ -562,11 +562,6 @@ Computes the singular value decomposition `A = USVh` of a matrix (or a stack of
 
         Each returned array must have the same floating-point data type as `x`.
 
-(function-linalg-tensordot)=
-### linalg.tensordot(x1, x2, /, *, axes=2)
-
-Alias for {ref}`function-tensordot`.
-
 (function-linalg-svdvals)=
 ### linalg.svdvals(x, /)
 
@@ -584,6 +579,11 @@ Computes the singular values of a matrix (or a stack of matrices) `x`.
 
     -   an array with shape `(..., K)` that contains the vector(s) of singular values of length `K`. For each vector, the singular values must be sorted in descending order by magnitude, such that `s[..., 0]` is the largest value, `s[..., 1]` is the second largest value, et cetera. The first `x.ndim-2` dimensions must have the same shape as those of the input `x`. The returned array must have the same floating-point data type as `x`.
 
+(function-linalg-tensordot)=
+### linalg.tensordot(x1, x2, /, *, axes=2)
+
+Alias for {ref}`function-tensordot`.
+
 (function-linalg-trace)=
 ### linalg.trace(x, /, *, offset=0)