chore: link to design topic

Author: kgryte

spec/draft/design_topics/copies_views_and_mutation.rst

@@ -79,6 +79,9 @@ standard, it remains possible to write code that will not work the same for all
 array libraries. This is something that the users are advised to best keep in
 mind and to reason carefully about the potential ambiguity of implemented code.
 
+
+.. _copy-keyword-argument:
+
 Copy keyword argument behavior
 ------------------------------
 

src/array_api_stubs/_draft/array_object.py

@@ -370,7 +370,7 @@ def __dlpack__(
             API standard.
         copy: Optional[bool]
             boolean indicating whether or not to copy the input. If ``True``, the
-            function must always copy (performed by the producer). If ``False``, the
+            function must always copy (performed by the producer; see also :ref:`copy-keyword-argument`). If ``False``, the
             function must never copy, and raise a ``BufferError`` in case a copy is
             deemed necessary (e.g. if a cross-device data movement is requested, and
             it is not possible without a copy). If ``None``, the function must reuse

src/array_api_stubs/_draft/creation_functions.py

@@ -111,7 +111,7 @@ def asarray(
     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]
-        boolean indicating whether or not to copy the input. If ``True``, the function must always copy. If ``False``, the function must never copy for input which supports the buffer protocol and must raise a ``ValueError`` in case a copy would be necessary. If ``None``, the function must reuse existing memory buffer if possible and copy otherwise. Default: ``None``.
+        boolean indicating whether or not to copy the input. If ``True``, the function must always copy (see :ref:`copy-keyword-argument`). If ``False``, the function must never copy for input which supports the buffer protocol and must raise a ``ValueError`` in case a copy would be necessary. If ``None``, the function must reuse existing memory buffer if possible and copy otherwise. Default: ``None``.
 
     Returns
     -------

src/array_api_stubs/_draft/data_type_functions.py

@@ -43,7 +43,7 @@ def astype(
     dtype: dtype
         desired data type.
     copy: bool
-        specifies whether to copy an array when the specified ``dtype`` matches the data type of the input array ``x``. If ``True``, a newly allocated array must always be returned. If ``False`` and the specified ``dtype`` matches the data type of the input array, the input array must be returned; otherwise, a newly allocated array must be returned. Default: ``True``.
+        specifies whether to copy an array when the specified ``dtype`` matches the data type of the input array ``x``. If ``True``, a newly allocated array must always be returned (see :ref:`copy-keyword-argument`). If ``False`` and the specified ``dtype`` matches the data type of the input array, the input array must be returned; otherwise, a newly allocated array must be returned. Default: ``True``.
     device: Optional[device]
         device on which to place the returned array. If ``device`` is ``None``, the output array device must be inferred from ``x``. Default: ``None``.
 

src/array_api_stubs/_draft/manipulation_functions.py

@@ -230,7 +230,7 @@ def reshape(
     shape: Tuple[int, ...]
         a new shape compatible with the original shape. One shape dimension is allowed to be ``-1``. When a shape dimension is ``-1``, the corresponding output array shape dimension must be inferred from the length of the array and the remaining dimensions.
     copy: Optional[bool]
-        whether or not to copy the input array. If ``True``, the function must always copy. If ``False``, the function must never copy. If ``None``, the function must avoid copying, if possible, and may copy otherwise. Default: ``None``.
+        whether or not to copy the input array. If ``True``, the function must always copy (see :ref:`copy-keyword-argument`). If ``False``, the function must never copy. If ``None``, the function must avoid copying, if possible, and may copy otherwise. Default: ``None``.
 
     Returns
     -------