Fix some style issues in docstrings, make pydocstyle check pass

The check to run is:
```
pydocstyle . --ignore=D401,D212,D413,D100 --match='(?!_types.py).*\.py'
```

`_types.py` is excluded because it's a private file, and it's too fiddly
and not necessary to add docstrings to the classes in that file.

Author: rgommers

spec/API_specification/array_api/__init__.py

@@ -1,3 +1,5 @@
+"""Function stubs and API documentation for the array API standard."""
+
 from .array_object import *
 from .constants import *
 from .creation_functions import *

spec/API_specification/array_api/_types.py

@@ -1,5 +1,5 @@
 """
-This file defines the types for type annotations.
+Types for type annotations used in the array API standard.
 
 The type variables should be replaced with the actual types for a given
 library, e.g., for NumPy TypeVar('array') would be replaced with ndarray.
@@ -33,6 +33,7 @@
 
 @dataclass
 class finfo_object:
+    """Dataclass returned by `finfo`."""
     bits: int
     eps: float
     max: float
@@ -42,6 +43,7 @@ class finfo_object:
 
 @dataclass
 class iinfo_object:
+    """Dataclass returned by `iinfo`."""
     bits: int
     max: int
     min: int

spec/API_specification/array_api/array_object.py

@@ -16,9 +16,7 @@
 
 class _array:
     def __init__(self: array) -> None:
-        """
-        Initialize the attributes for the array object class.
-        """
+        """Initialize the attributes for the array object class."""
 
     @property
     def dtype(self: array) -> Dtype:

spec/API_specification/array_api/creation_functions.py

@@ -156,7 +156,7 @@ def eye(
     dtype: Optional[dtype] = None,
     device: Optional[device] = None,
 ) -> array:
-    """
+    r"""
     Returns a two-dimensional array with ones on the ``k``\th diagonal and zeros elsewhere.
 
     .. note::

spec/API_specification/array_api/linalg.py

@@ -228,9 +228,7 @@ def inv(x: array, /) -> array:
 
 
 def matmul(x1: array, x2: array, /) -> array:
-    """
-    Alias for :func:`~array_api.matmul`.
-    """
+    """Alias for :func:`~array_api.matmul`."""
 
 
 def matrix_norm(
@@ -332,9 +330,7 @@ def matrix_rank(x: array, /, *, rtol: Optional[Union[float, array]] = None) -> a
 
 
 def matrix_transpose(x: array, /) -> array:
-    """
-    Alias for :func:`~array_api.matrix_transpose`.
-    """
+    """Alias for :func:`~array_api.matrix_transpose`."""
 
 
 def outer(x1: array, x2: array, /) -> array:
@@ -603,9 +599,7 @@ def tensordot(
     *,
     axes: Union[int, Tuple[Sequence[int], Sequence[int]]] = 2,
 ) -> array:
-    """
-    Alias for :func:`~array_api.tensordot`.
-    """
+    """Alias for :func:`~array_api.tensordot`."""
 
 
 def trace(x: array, /, *, offset: int = 0, dtype: Optional[dtype] = None) -> array:
@@ -660,9 +654,7 @@ def trace(x: array, /, *, offset: int = 0, dtype: Optional[dtype] = None) -> arr
 
 
 def vecdot(x1: array, x2: array, /, *, axis: int = None) -> array:
-    """
-    Alias for :func:`~array_api.vecdot`.
-    """
+    """Alias for :func:`~array_api.vecdot`."""
 
 
 def vector_norm(

spec/API_specification/array_api/linear_algebra_functions.py

@@ -105,7 +105,7 @@ def tensordot(
 
 
 def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array:
-    """
+    r"""
     Computes the (vector) dot product of two arrays.
 
     Let :math:`\mathbf{a}` be a vector in ``x1`` and :math:`\mathbf{b}` be a corresponding vector in ``x2``. The dot product is defined as

spec/API_specification/array_api/manipulation_functions.py

@@ -190,7 +190,7 @@ def stack(arrays: Union[Tuple[array, ...], List[array]], /, *, axis: int = 0) ->
         axis along which the arrays will be joined. Providing an ``axis`` specifies the index of the new axis in the dimensions of the result. For example, if ``axis`` is ``0``, the new axis will be the first dimension and the output array will have shape ``(N, A, B, C)``; if ``axis`` is ``1``, the new axis will be the second dimension and the output array will have shape ``(A, N, B, C)``; and, if ``axis`` is ``-1``, the new axis will be the last dimension and the output array will have shape ``(A, B, C, N)``. A valid ``axis`` must be on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If provided an ``axis`` outside of the required interval, the function must raise an exception. Default: ``0``.
 
     Returns
-    --------
+    -------
     out: array
         an output array having rank ``N+1``, where ``N`` is the rank (number of dimensions) of ``x``. If the input arrays have different data types, normal :ref:`type-promotion` must apply. If the input arrays have the same data type, the output array must have the same data type as the input arrays.