Apply suggestions from code review

Author: leofang

spec/API_specification/array_api/fourier_transform_functions.py

@@ -88,18 +88,17 @@ def fftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, no
     s: Sequence[int]
         size of each transformed axis of the output. If
 
-        - ``s[i]`` is greater than the size of the input array along a corresponding axis (dimension) ``j``, the corresponding axis of the input array must be zero-padded such that the axis has size ``s[i]``.
-        - ``s[i]`` is less than the size of the input array along a corresponding axis (dimension) ``j``, the corresponding axis of the input array must be trimmed such that the axis has size``s[i]``.
+        - ``s[i]`` is greater than the size of the input array along a corresponding axis (dimension) ``i``, the corresponding axis of the input array must be zero-padded such that the axis has size ``s[i]``.
+        - ``s[i]`` is less than the size of the input array along a corresponding axis (dimension) ``i``, the corresponding axis of the input array must be trimmed such that the axis has size ``s[i]``.
 
-        If ``axes`` is ``None``, the last ``len(s)`` axes must be transformed, and, thus, ``j`` represents an axis index computed according to ``N - len(s) + i``, where ``N`` is the number of axes (e.g., if ``N = 4`` and ``s = (256, 256)``, then ``i = 0`` corresponds to axis ``2`` and ``i = 1`` corresponds to axis ``3``, the last axis).
 
         If ``axes`` is not ``None``, size ``s[i]`` corresponds to the size of axis ``axes[j]`` where ``i == j``.
 
         If not provided, the size of each transformed axis (dimension) in the output array must equal the size of the corresponding axis in the input array.
 
         Default: ``None``.
     axes: Sequence[int]
-        axes (dimension) over which to compute the Fourier transform. If ``None`` and ``s`` is not specified, all axes must be transformed. If ``None`` and ``s`` is specified, the last ``len(s)`` axes must be transformed. Default: ``None``.
+        axes (dimension) over which to compute the Fourier transform. If ``None`` and ``s`` is not specified, all axes must be transformed. If ``s`` is specified, the corresponding ``axes`` to be transformed must be explicitly specified too. Default: ``None``.
     norm: Literal['backward', 'ortho', 'forward']
         normalization mode. Should be one of the following modes:
 
@@ -203,8 +202,8 @@ def irfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal
     n: int
         length of the transformed axis of the **output**. If
 
-        - ``n`` is greater than the length of the input array, the input array must be zero-padded such that the input array has length ``n``.
-        - ``n`` is less than the length of the input array, the input array must be trimmed to length ``n//2+1``.
+        - ``n//2+1`` is greater than the length of the input array, the input array must be zero-padded.
+        - ``n//2+1`` is less than the length of the input array, the input array must be trimmed.
 
         If not provided, the length of the transformed axis of the output must equal the length ``2 * (m - 1)`` where ``m`` is the length of the input along the axis specified by ``axis``. Default: ``None``.
     axis: int
@@ -343,7 +342,7 @@ def ihfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal
     x: array
         input array. Should have a real-valued floating-point data type.
     n: int
-        length of the transformed axis of the output. If
+        length of the transformed axis of the **input**. If
 
         - ``n`` is greater than the length of the input array, the input array must be zero-padded such that the input array has length ``n``.
         - ``n`` is less than the length of the input array, the input array must be trimmed to length ``n``.
@@ -365,7 +364,7 @@ def ihfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal
     Returns
     -------
     out: array
-        an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`.
+        an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex-valued floating-point data type determined by :ref:`type-promotion`.
     """
 
 
@@ -375,11 +374,10 @@ def fftfreq(n: int, /, *, d: float = 1.0):
 
     For a Fourier transform of length ``n`` and length unit of ``d`` the frequencies are described as:
 
-
     .. code-block::
 
-      f = [0, 1, ..., n/2-1, -n/2, ..., -1] / (d*n) if n is even
-      f = [0, 1, ..., (n-1)/2, -(n-1)/2, ..., -1] / (d*n) if n is odd
+      f = [0, 1, ..., n/2-1, -n/2, ..., -1] / (d*n)       # if n is even
+      f = [0, 1, ..., (n-1)/2, -(n-1)/2, ..., -1] / (d*n) # if n is odd
 
     Parameters
     ----------
@@ -397,13 +395,14 @@ def fftfreq(n: int, /, *, d: float = 1.0):
 
 def rfftfreq(n: int, /, *, d: float = 1.0):
     """
-    Returns the discrete Fourier transform sample frequencies. For a Fourier transform of length ``n`` and length unit of ``d`` the frequencies are described as:
-
+    Returns the discrete Fourier transform sample frequencies (for ``rfft`` and ``irfft``). 
+    
+    For a Fourier transform of length ``n`` and length unit of ``d`` the frequencies are described as:
 
     .. code-block::
 
-      f = [0, 1, ..., n/2-1, -n/2, ..., -1] / (d*n) if n is even
-      f = [0, 1, ..., (n-1)/2, -(n-1)/2, ..., -1] / (d*n) if n is odd
+      f = [0, 1, ...,     n/2-1,     n/2] / (d*n)  # if n is even
+      f = [0, 1, ..., (n-1)/2-1, (n-1)/2] / (d*n)  # if n is odd
 
     The Nyquist frequency component is considered to be positive.
 
@@ -417,15 +416,15 @@ def rfftfreq(n: int, /, *, d: float = 1.0):
     Returns
     -------
     out: array
-        an array of length ``n`` containing the sample frequencies. The returned array must have a floating-point data type determined by :ref:`type-promotion`.
+        an array of length ``n//2+1`` containing the sample frequencies. The returned array must have a floating-point data type determined by :ref:`type-promotion`.
     """
 
 
 def fftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None):
     """
     Shift the zero-frequency component to the center of the spectrum.
 
-    This function swaps half-spaces for all axes (dimensions) specified by `axes`.
+    This function swaps half-spaces for all axes (dimensions) specified by ``axes``.
 
     .. note::
        ``out[0]`` is the Nyquist component only if the length of the input is even.
@@ -449,7 +448,7 @@ def ifftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None):
     Inverse of ``fftshift``.
 
     .. note::
-       Although identical for even-length ``x``, ``fftshift`` and `ifftshift`` differ by one sample for odd-length ``x``.
+       Although identical for even-length ``x``, ``fftshift`` and ``ifftshift`` differ by one sample for odd-length ``x``.
 
     Parameters
     ----------