docs: clarify that behavior when provided a nested sequence to asarray is unspecified

ev-br · kgryte · lucascolley · web-flow · commit 3267c1845c3f · 2025-05-26T00:35:16.000-07:00
PR-URL: #917 Ref: data-apis/array-api-strict#118 Co-authored-by: Athan Reines <kgryte@gmail.com> Reviewed-by: Athan Reines <kgryte@gmail.com> Co-authored-by: Lucas Colley <lucas.colley8@gmail.com> Reviewed-by: Lucas Colley <lucas.colley8@gmail.com>
diff --git a/src/array_api_stubs/_draft/creation_functions.py b/src/array_api_stubs/_draft/creation_functions.py
@@ -101,14 +101,6 @@ def asarray(
 
         Default: ``None``.
 
-        .. admonition:: Note
-           :class: note
-
-           If ``dtype`` is not ``None``, then array conversions should obey :ref:`type-promotion` rules. Conversions not specified according to :ref:`type-promotion` rules may or may not be permitted by a conforming array library. To perform an explicit cast, use :func:`array_api.astype`.
-
-        .. note::
-           If an input value exceeds the precision of the resolved output array data type, behavior is left unspecified and, thus, implementation-defined.
-
     device: Optional[device]
         device on which to place the created array. If ``device`` is ``None`` and ``obj`` is an array, the output array device must be inferred from ``obj``. Default: ``None``.
     copy: Optional[bool]
@@ -122,6 +114,10 @@ def asarray(
     Notes
     -----
 
+    -   If ``obj`` is a sequence with some elements being arrays, behavior is unspecified and thus implementation-defined. Conforming implementations may perform a conversion or raise an exception. To join a sequence of arrays along a new axis, see :func:`~array_api.stack`.
+    -   If ``dtype`` is not ``None``, then array conversions should obey :ref:`type-promotion` rules. Conversions not specified according to :ref:`type-promotion` rules may or may not be permitted by a conforming array library. To perform an explicit cast, use :func:`array_api.astype`.
+    -   If an input value exceeds the precision of the resolved output array data type, behavior is unspecified and thus implementation-defined.
+
     .. versionchanged:: 2022.12
        Added complex data type support.
     """
