From db2b3bccf31a11d1f3079a7bcf36df1bd563ffc2 Mon Sep 17 00:00:00 2001
From: Bouwe Andela <b.andela@esciencecenter.nl>
Date: Mon, 11 Dec 2023 13:05:21 +0100
Subject: [PATCH] Document the behaviour of converting a Dask array to a Python
 number

---
 dask/array/core.py        | 15 +++++++++++++++
 docs/source/array-api.rst |  5 +++++
 2 files changed, 20 insertions(+)

diff --git a/dask/array/core.py b/dask/array/core.py
index 56691c42685..5d9d11cee7f 100644
--- a/dask/array/core.py
+++ b/dask/array/core.py
@@ -1858,6 +1858,9 @@ def to_backend(self, backend: str | None = None, **kwargs):
         return to_backend(self, backend=backend, **kwargs)
 
     def __bool__(self):
+        """Compute the value of a length-1 array and convert it to
+        :class:`bool`.
+        """
         if self.size > 1:
             raise ValueError(
                 f"The truth value of a {self.__class__.__name__} is ambiguous. "
@@ -1875,17 +1878,29 @@ def _scalarfunc(self, cast_type):
             return cast_type(self.compute().item())
 
     def __int__(self):
+        """Compute the value of a length-1 array and convert it to
+        :class:`int`.
+        """
         return self._scalarfunc(int)
 
     __long__ = __int__  # python 2
 
     def __float__(self):
+        """Compute the value of a length-1 array and convert it to
+        :class:`float`.
+        """
         return self._scalarfunc(float)
 
     def __complex__(self):
+        """Compute the value of a length-1 array and convert it to
+        :class:`complex`.
+        """
         return self._scalarfunc(complex)
 
     def __index__(self):
+        """Compute the value of a length-1 array and pass it to
+        :func:`operator.index`.
+        """
         return self._scalarfunc(operator.index)
 
     def __setitem__(self, key, value):
diff --git a/docs/source/array-api.rst b/docs/source/array-api.rst
index b7964261392..5f1716c1ae1 100644
--- a/docs/source/array-api.rst
+++ b/docs/source/array-api.rst
@@ -320,6 +320,11 @@ Array
    Array.view
    Array.vindex
    Array.visualize
+   Array.__bool__
+   Array.__complex__
+   Array.__float__
+   Array.__index__
+   Array.__int__
 
 
 Fast Fourier Transforms