Merge pull request #956 from rust-ndarray/axis-axes-cleanup

Elaborate doc for Axis and fix an example for Axes

Author: bluss

src/dimension/axes.rs

@@ -1,7 +1,7 @@
 use crate::{Axis, Dimension, Ix, Ixs};
 
 /// Create a new Axes iterator
-pub fn axes_of<'a, D>(d: &'a D, strides: &'a D) -> Axes<'a, D>
+pub(crate) fn axes_of<'a, D>(d: &'a D, strides: &'a D) -> Axes<'a, D>
 where
     D: Dimension,
 {
@@ -15,9 +15,10 @@ where
 
 /// An iterator over the length and stride of each axis of an array.
 ///
-/// See [`.axes()`](../struct.ArrayBase.html#method.axes) for more information.
+/// This iterator is created from the array method
+/// [`.axes()`](crate::ArrayBase::axes).
 ///
-/// Iterator element type is `AxisDescription`.
+/// Iterator element type is [`AxisDescription`].
 ///
 /// # Examples
 ///
@@ -27,10 +28,14 @@ where
 ///
 /// let a = Array3::<f32>::zeros((3, 5, 4));
 ///
+/// // find the largest axis in the array
+/// // check the axis index and its length
+///
 /// let largest_axis = a.axes()
-///                     .max_by_key(|ax| ax.len())
-///                     .unwrap().axis();
-/// assert_eq!(largest_axis, Axis(1));
+///                     .max_by_key(|ax| ax.len)
+///                     .unwrap();
+/// assert_eq!(largest_axis.axis, Axis(1));
+/// assert_eq!(largest_axis.len, 5);
 /// ```
 #[derive(Debug)]
 pub struct Axes<'a, D> {

src/dimension/axis.rs

@@ -8,11 +8,21 @@
 
 /// An axis index.
 ///
-/// An axis one of an array’s “dimensions”; an *n*-dimensional array has *n* axes.
-/// Axis *0* is the array’s outermost axis and *n*-1 is the innermost.
+/// An axis one of an array’s “dimensions”; an *n*-dimensional array has *n*
+/// axes.  Axis *0* is the array’s outermost axis and *n*-1 is the innermost.
 ///
 /// All array axis arguments use this type to make the code easier to write
 /// correctly and easier to understand.
+/// 
+/// For example: in a method like `index_axis(axis, index)` the code becomes
+/// self-explanatory when it's called like `.index_axis(Axis(1), i)`; it's
+/// evident which integer is the axis number and which is the index.
+///
+/// Note: This type does **not** implement From/Into usize and similar trait
+/// based conversions, because we want to preserve code readability and quality.
+///
+/// `Axis(1)` in itself is a very clear code style and the style that should be
+/// avoided is code like `1.into()`.
 #[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
 pub struct Axis(pub usize);
 

src/dimension/mod.rs

@@ -11,7 +11,8 @@ use crate::slice::SliceArg;
 use crate::{Ix, Ixs, Slice, SliceInfoElem};
 use num_integer::div_floor;
 
-pub use self::axes::{axes_of, Axes, AxisDescription};
+pub use self::axes::{Axes, AxisDescription};
+pub(crate) use self::axes::axes_of;
 pub use self::axis::Axis;
 pub use self::broadcast::DimMax;
 pub use self::conversion::IntoDimension;

src/impl_2d.rs

@@ -118,6 +118,7 @@ where
     /// assert!(!array.is_square());
     /// ```
     pub fn is_square(&self) -> bool {
-        self.nrows() == self.ncols()
+        let (m, n) = self.dim();
+        m == n
     }
 }