From a5a4b9819d442d2d5b41bbf003d7f02a62e23fda Mon Sep 17 00:00:00 2001
From: Ulrik Sverdrup <bluss@users.noreply.github.com>
Date: Sat, 9 Mar 2024 11:49:47 +0100
Subject: [PATCH] shape: More explicit examples for to_shape and into_shape

---
 src/impl_methods.rs | 30 ++++++++++++++++++++++++++----
 1 file changed, 26 insertions(+), 4 deletions(-)

diff --git a/src/impl_methods.rs b/src/impl_methods.rs
index f07ecb43a..0f97aeb8d 100644
--- a/src/impl_methods.rs
+++ b/src/impl_methods.rs
@@ -1815,9 +1815,20 @@ where
     /// number of rows and columns (or more axes if applicable), it is important to pick an index
     /// ordering, and that's the reason for the function parameter for `order`.
     ///
+    /// The `new_shape` parameter should be a dimension and an optional order like these examples:
+    ///
+    /// ```text
+    /// (3, 4)                          // Shape 3 x 4 with default order (RowMajor)
+    /// ((3, 4), Order::RowMajor))      // use specific order
+    /// ((3, 4), Order::ColumnMajor))   // use specific order
+    /// ((3, 4), Order::C))             // use shorthand for order - shorthands C and F
+    /// ```
+    ///
     /// **Errors** if the new shape doesn't have the same number of elements as the array's current
     /// shape.
     ///
+    /// # Example
+    ///
     /// ```
     /// use ndarray::array;
     /// use ndarray::Order;
@@ -1890,10 +1901,10 @@ where
     ///
     /// If an index ordering is not specified, the default is `RowMajor`.
     /// The operation will only succeed if the array's memory layout is compatible with
-    /// the index ordering.
+    /// the index ordering, so that the array elements can be rearranged in place.
     ///
-    /// Use `.to_shape()` instead for more flexible reshaping of arrays, which
-    /// allows copying elements if required.
+    /// If required use `.to_shape()` or `.into_shape_clone` instead for more flexible reshaping of
+    /// arrays, which allows copying elements if required.
     ///
     /// **Errors** if the shapes don't have the same number of elements.<br>
     /// **Errors** if order RowMajor is given but input is not c-contiguous.
@@ -1903,6 +1914,17 @@ where
     /// reshaped using row major index ordering, column major arrays with column major index
     /// ordering.
     ///
+    /// The `new_shape` parameter should be a dimension and an optional order like these examples:
+    ///
+    /// ```text
+    /// (3, 4)                          // Shape 3 x 4 with default order (RowMajor)
+    /// ((3, 4), Order::RowMajor))      // use specific order
+    /// ((3, 4), Order::ColumnMajor))   // use specific order
+    /// ((3, 4), Order::C))             // use shorthand for order - shorthands C and F
+    /// ```
+    ///
+    /// # Example
+    ///
     /// ```
     /// use ndarray::{aview1, aview2};
     /// use ndarray::Order;
@@ -1960,7 +1982,7 @@ where
     /// is C-contig or F-contig, it follows the index order that corresponds to the memory order.
     /// Prefer to use `.to_shape()` or `.into_shape_with_order()`.
     ///
-    /// Because of this, the method is deprecated. That reshapes depend on memory order is not
+    /// Because of this, the method **is deprecated**. That reshapes depend on memory order is not
     /// intuitive.
     ///
     /// **Errors** if the shapes don't have the same number of elements.<br>