Apply review comments

Author: mtsokol

spec/2025.12/migration_guide.md

@@ -29,33 +29,39 @@ a set of tools and packages to help you with the migration process:
 ### Array API Compat
 
 GitHub: [array-api-compat](https://github.com/data-apis/array-api-compat)
+User group: Array Consumers
 
 Although NumPy, Dask, CuPy, and PyTorch support the Array API Standard, there
 are still some corner cases where their behavior diverges from the standard.
 `array-api-compat` provides a compatibility layer to cover these cases as well.
 This is also accompanied by a few utility functions for easier introspection
-into array objects.
+into array objects. As an array consumer you can still rely on the original API
+while having access to the standard compatible one.
 
 
 (array-api-strict)=
 
 ### Array API Strict
 
 GitHub: [array-api-strict](https://github.com/data-apis/array-api-strict)
+User group: Array Consumers, Array Producers (for testing)
 
 `array-api-strict` is a library that provides a strict and minimal
-implementation of the Array API Standard. It is designed to be used as
-a reference implementation for testing and development purposes. By comparing
-your API calls with `array-api-strict` counterparts, you can ensure that your
-library is fully compliant with the standard and can serve as a reliable
-reference for other developers in the ecosystem.
+implementation of the Array API Standard. For array producers it is designed
+to be used as a reference implementation for testing and development purposes.
+You can compare your API calls with `array-api-strict` counterparts,
+and ensure that your library is fully compliant with the standard and can
+serve as a reliable reference for other developers in the ecosystem.
+For consumers you can use `array-api-strict` during the development as an
+array provider to ensure your code uses API compliant with the standard.
 
 
 (array-api-tests)=
 
 ### Array API Test
 
 GitHub: [array-api-tests](https://github.com/data-apis/array-api-tests)
+User group: Array Producers
 
 `array-api-tests` is a collection of tests that can be used to verify the
 compliance of your library with the Array API Standard. It includes tests
@@ -69,6 +75,7 @@ standard and can be used with compatible array consumers libraries.
 ### Array API Extra
 
 GitHub: [array-api-extra](https://github.com/data-apis/array-api-extra)
+User group: Array Consumers
 
 `array-api-extra` is a collection of additional utilities and tools that are
 missing from the Array API Standard but can be useful for compliant array
@@ -103,7 +110,8 @@ reference implementation.
 {ref}`array-api-tests` is a test suite which verifies that your API
 for adhering to the standard. For each function or method it confirms
 it's importable, verifies the signature, and generates multiple test
-cases with hypothesis package and runs asserts for the outputs.
+cases with [hypothesis](https://hypothesis.readthedocs.io/en/latest/)
+package and runs asserts for the outputs.
 
 The setup details are enclosed in the GitHub repository, so here we
 cover only the minimal workflow:
@@ -113,17 +121,20 @@ cover only the minimal workflow:
    variable to your package import name.
 3. Inside the `array-api-tests` directory run `pytest` command. There are
    multiple useful options delivered by the test suite, a few worth mentioning:
-   - `--max-examples=2` - maximal number of test cases to generate by the
+   - `--max-examples=1000` - maximal number of test cases to generate by the
      hypothesis. This allows you to balance between execution time of the test
-     suite and thoroughness of the testing.
+     suite and thoroughness of the testing. It's advised to use as many examples
+     as the time buget can fit. Each test case is a random combination of
+     possible inputs: the more cases, the higher chance of finding an unsupported
+     edge case.
    - With `--xfails-file` option you can describe which tests are expected to
      fail - it's impossible to get the whole API perfectly implemented on a
      first try, so tracking what still fails gives you more control over the
      state of your API.
    - `-o xfail_strict=<bool>` is often used with the previous one. If a test
      expected to fail actually passes (`XPASS`) then you can decide whether
      to ignore that fact or raise it as an error.
-   - `--skips-file` for skipping files. At times some failing tests might stall
+   - `--skips-file` for skipping tests. At times some failing tests might stall
      the execution time of the test suite - in that case the most convenient
      option is to skip these for the time being.
 
@@ -138,15 +149,15 @@ A simpler, and more manual, way of testing the Array API coverage is to
 run your API calls along with {ref}`array-api-strict` Python implementation.
 
 This way you can ensure the outputs coming from your API match the minimal
-reference implementation, but bare in mind you need to write the tests cases
+reference implementation, but bear in mind you need to write the tests cases
 yourself, so you need to also take into account the edge cases as well.
 
 
 (array-consumers)=
 
 ## Array Consumers
 
-For array consumers the main premise is keep in mind that your **array
+For array consumers the main premise is to keep in mind that your **array
 manipulation operations should not lock in for a particular array producing
 library**. For instance, if you use NumPy for arrays, then your code could
 contain:
@@ -162,8 +173,9 @@ return np.dot(c, b)
 
 The first step should be as simple as assigning `np` namespace to a dedicated
 namespace variable - the convention in the ecosystem is to name it `xp`. Then
-Making sure that each method and function call is something that Array API
-supports is vital (we will get to that soon):
+making sure that each method and function call is something that Array API
+supports is vital. `dot` is present in the NumPy's API but the standard doesn't
+support it. Let's use `tensordot` instead - both NumPy and the standard define it:
 
 ```python
 import numpy as np
@@ -180,12 +192,23 @@ Then replacing one backend with another one should rely on providing a different
 namespace, such as: `xp = torch`, e.g. via environment variable. This can be useful
 if you're writing a script or in your custom software. The other alternatives are:
 
-- If you are building a library where the backend is determined by input arrays
-  passed by the end-user, then a recommended way is to ask your input arrays for a
-  namespace to use: `xp = arr.__array_namespace__()`
-- Each function you implement can have a namespace `xp` as a parameter in the
-  signature. Then enforcing inputs to be of type by the provided backend can be
-  achieved with `arg1 = xp.asarray(arg1)` for each input array.
+- If you are building a library where the backend is determined by input arrays,
+  and your function accepts array arguments, then a recommended way is to ask
+  your input arrays for a namespace to use: `xp = arr.__array_namespace__()`.
+  If the given library doesn't have it, then [`array_api_compat.array_namespace()`](https://data-apis.org/array-api-compat/helper-functions.html#array_api_compat.array_namespace)
+  should be used instead:
+  ```python
+  def func(array1, scalar1, scalar2):
+    xp = array1.__array_namespace__()  # or array_namespace(array1)
+    return xp.arange(scalar1, scalar2) @ array1
+  ```
+- For a function that accepts scalars and returns arrays, use namespace `xp` as
+  a parameter in the signature. Then enforcing objects to be of type by the
+  provided backend can be achieved with `arg1 = xp.asarray(arg1)` for each input:
+  ```python
+  def func(s1, s2, xp):
+    return xp.arange(s1, s2)
+  ```
 
 If you're relying on NumPy, CuPy, PyTorch, Dask, or JAX then
 {ref}`array-api-compat` can come in handy for the transition. The compat layer

spec/2025.12/tutorial_basic.md

@@ -108,5 +108,51 @@ def is_converged(xprev, x, N, tol):
 
 At this point the actual execution depends only on `xp` namespace,
 and replacing that one variable allow us to switch from e.g. NumPy arrays
-to a JAX execution on a GPU. This allows us to be more flexible, and, for
-example use lazy evaluation and JIT compile a loop body with JAX's JIT compilation.
+to a JAX execution on a GPU. This lets us be more flexible, and, for example,
+use lazy evaluation and JIT compile a loop body with JAX's JIT compilation:
+
+```python
+import jax
+import jax.numpy as jnp
+
+xp = jnp
+
+def hits(G, max_iter=100, tol=1.0e-8, normalized=True):
+    N = len(G)
+    h = xp.full((N, 1), 1.0 / N)
+    A = xp.asarray(G.A)
+    # Power iteration: make up to max_iter iterations
+    for _i in range(max_iter):
+        h, a, conv = loop_body(h, A, N, tol)
+        if conv:
+            break
+    else:
+        raise Exception("Didn't converge")
+    if normalized:
+        h = h / xp.sum(xp.abs(h))
+        a = a / xp.sum(xp.abs(a))
+    return h, a
+
+@jax.jit
+def loop_body(hprev, A, N, tol):
+    a = hprev.mT @ A
+    h = A @ a.mT
+    h = h / xp.max(h)
+    conv = is_converged(hprev, h, N, tol)
+    return h, a, conv
+
+def is_converged(xprev, x, N, tol):
+    err = xp.sum(xp.abs(x - xprev))
+    return err < xp.asarray(N * tol)
+
+if __name__ == "__main__":
+
+    class Graph():
+        def __init__(self):
+            self.A = xp.ones((10, 10))
+        def __len__(self):
+            return len(self.A)
+
+    G = Graph()
+    h, a = hits(G)
+```