DOC: improve ascontiguousarray() and asfortranarray() examples (n…

…umpy#21501)

Right now, example for ascontiguousarray() only demonstrates that the function is capable to change the dtype, but it doesn't really change the memory layout since x is already C_CONTIGUOUS. In this PR we make this example more relevant and be consistent with the example for asfortranarray().

* DOC: make examples for `ascontiguousarray()` and `asfortranarray()` to be consistent

* Add more examples

* Get rid of .reshape()

* Reduce line length to 79 chars

* Change order of examples, remove trailing comments

* Use two-space indent

* Change `::` to `:`, remove code indentation

numpy/core/_add_newdocs.py

@@ -1084,13 +1084,32 @@
 
     Examples
     --------
-    >>> x = np.arange(6).reshape(2,3)
-    >>> np.ascontiguousarray(x, dtype=np.float32)
-    array([[0., 1., 2.],
-           [3., 4., 5.]], dtype=float32)
+    Starting with a Fortran-contiguous array:
+
+    >>> x = np.ones((2, 3), order='F')
+    >>> x.flags['F_CONTIGUOUS']
+    True
+
+    Calling ``ascontiguousarray`` makes a C-contiguous copy:
+
+    >>> y = np.ascontiguousarray(x)
+    >>> y.flags['C_CONTIGUOUS']
+    True
+    >>> np.may_share_memory(x, y)
+    False
+
+    Now, starting with a C-contiguous array:
+
+    >>> x = np.ones((2, 3), order='C')
     >>> x.flags['C_CONTIGUOUS']
     True
 
+    Then, calling ``ascontiguousarray`` returns the same object:
+
+    >>> y = np.ascontiguousarray(x)
+    >>> x is y
+    True
+
     Note: This function returns an array with at least one-dimension (1-d)
     so it will not preserve 0-d arrays.
 
@@ -1130,12 +1149,31 @@
 
     Examples
     --------
-    >>> x = np.arange(6).reshape(2,3)
+    Starting with a C-contiguous array:
+
+    >>> x = np.ones((2, 3), order='C')
+    >>> x.flags['C_CONTIGUOUS']
+    True
+
+    Calling ``asfortranarray`` makes a Fortran-contiguous copy:
+
     >>> y = np.asfortranarray(x)
-    >>> x.flags['F_CONTIGUOUS']
-    False
     >>> y.flags['F_CONTIGUOUS']
     True
+    >>> np.may_share_memory(x, y)
+    False
+
+    Now, starting with a Fortran-contiguous array:
+
+    >>> x = np.ones((2, 3), order='F')
+    >>> x.flags['F_CONTIGUOUS']
+    True
+
+    Then, calling ``asfortranarray`` returns the same object:
+
+    >>> y = np.asfortranarray(x)
+    >>> x is y
+    True
 
     Note: This function returns an array with at least one-dimension (1-d)
     so it will not preserve 0-d arrays.