Clarify order of indices returned in dpnp.tril_indices and dpnp.triu_indices

CHANGELOG.md

@@ -43,6 +43,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Extended `dpnp.pad` to support `pad_width` keyword as a dictionary [#2535](https://github.com/IntelPython/dpnp/pull/2535)
 * Redesigned `dpnp.erf` function through pybind11 extension of OneMKL call or dedicated kernel in `ufunc` namespace [#2551](https://github.com/IntelPython/dpnp/pull/2551)
 * Improved performance of batched implementation of `dpnp.linalg.det` and `dpnp.linalg.slogdet` [#2572](https://github.com/IntelPython/dpnp/pull/2572)
+* Improved documentations of `dpnp.tril_indices` and `dpnp.triu_indices` to clarify the returned order of indices [#2586](https://github.com/IntelPython/dpnp/pull/2586)
 
 ### Deprecated
 

dpnp/dpnp_iface_indexing.py

@@ -2375,8 +2375,9 @@ def tril_indices(
     Returns
     -------
     inds : tuple of dpnp.ndarray
-        The indices for the triangle. The returned tuple contains two arrays,
-        each with the indices along one dimension of the array.
+        The row and column indices, respectively. The row indices are sorted in
+        non-decreasing order, and the corresponding column indices are strictly
+        increasing for each row.
 
     See Also
     --------
@@ -2394,7 +2395,13 @@ def tril_indices(
 
     >>> import dpnp as np
     >>> il1 = np.tril_indices(4)
-    >>> il2 = np.tril_indices(4, 2)
+    >>> il1
+    (array([0, 1, 1, 2, 2, 2, 3, 3, 3, 3]),
+     array([0, 0, 1, 0, 1, 2, 0, 1, 2, 3]))
+
+    Note that row indices (first array) are non-decreasing, and the
+    corresponding column indices (second array) are strictly increasing for
+    each row.
 
     Here is how they can be used with a sample array:
 
@@ -2421,6 +2428,7 @@ def tril_indices(
 
     These cover almost the whole array (two diagonals right of the main one):
 
+    >>> il2 = np.tril_indices(4, 2)
     >>> a[il2] = -10
     >>> a
     array([[-10, -10, -10,   3],
@@ -2584,9 +2592,9 @@ def triu_indices(
     Returns
     -------
     inds : tuple of dpnp.ndarray
-        The indices for the triangle. The returned tuple contains two arrays,
-        each with the indices along one dimension of the array. Can be used
-        to slice a ndarray of shape(`n`, `n`).
+        The row and column indices, respectively. The row indices are sorted in
+        non-decreasing order, and the corresponding column indices are strictly
+        increasing for each row.
 
     See Also
     --------
@@ -2604,7 +2612,13 @@ def triu_indices(
 
     >>> import dpnp as np
     >>> iu1 = np.triu_indices(4)
-    >>> iu2 = np.triu_indices(4, 2)
+    >>> iu1
+    (array([0, 0, 0, 0, 1, 1, 1, 2, 2, 3]),
+     array([0, 1, 2, 3, 1, 2, 3, 2, 3, 3]))
+
+    Note that row indices (first array) are non-decreasing, and the
+    corresponding column indices (second array) are strictly increasing for
+    each row.
 
     Here is how they can be used with a sample array:
 
@@ -2632,6 +2646,7 @@ def triu_indices(
     These cover only a small part of the whole array (two diagonals right
     of the main one):
 
+    >>> iu2 = np.triu_indices(4, 2)
     >>> a[iu2] = -10
     >>> a
     array([[ -1,  -1, -10, -10],