Improve docs related to subviews

Author: jturner314

src/impl_methods.rs

@@ -542,8 +542,8 @@ impl<A, S, D> ArrayBase<S, D> where S: Data<Elem=A>, D: Dimension
         }
     }
 
-    /// Along `axis`, select the subview `index` and return a
-    /// view with that axis removed.
+    /// Returns a view restricted to `index` along the axis, with the axis
+    /// removed.
     ///
     /// See [*Subviews*](#subviews) for full documentation.
     ///
@@ -570,8 +570,8 @@ impl<A, S, D> ArrayBase<S, D> where S: Data<Elem=A>, D: Dimension
         self.view().index_axis_move(axis, index)
     }
 
-    /// Along `axis`, select the subview `index` and return a read-write view
-    /// with the axis removed.
+    /// Returns a mutable view restricted to `index` along the axis, with the
+    /// axis removed.
     ///
     /// **Panics** if `axis` or `index` is out of bounds.
     ///
@@ -602,10 +602,11 @@ impl<A, S, D> ArrayBase<S, D> where S: Data<Elem=A>, D: Dimension
         self.view_mut().index_axis_move(axis, index)
     }
 
-    /// Along `axis`, select the subview `index` and return `self`
-    /// with that axis removed.
+    /// Collapses the array to `index` along the axis and removes the axis.
     ///
     /// See [`.index_axis()`](#method.index_axis) and [*Subviews*](#subviews) for full documentation.
+    ///
+    /// **Panics** if `axis` or `index` is out of bounds.
     pub fn index_axis_move(mut self, axis: Axis, index: usize) -> ArrayBase<S, D::Smaller>
     where
         D: RemoveAxis,
@@ -614,10 +615,9 @@ impl<A, S, D> ArrayBase<S, D> where S: Data<Elem=A>, D: Dimension
         self.remove_axis(axis)
     }
 
-    /// Collapse the axis into length one, selecting the subview at the given
-    /// `index` along the axis.
+    /// Selects `index` along the axis, collapsing the axis into length one.
     ///
-    /// **Panics** if `index` is past the length of the axis.
+    /// **Panics** if `axis` or `index` is out of bounds.
     pub fn collapse_axis(&mut self, axis: Axis, index: usize) {
         dimension::do_collapse_axis(
             &mut self.dim,

src/lib.rs

@@ -452,10 +452,11 @@ pub type Ixs = isize;
 ///
 /// [`&SliceInfo`]: struct.SliceInfo.html
 ///
-/// If a range is used, the axis is preserved. If an index is used, a subview
-/// is taken with respect to the axis. See [*Subviews*](#subviews) for more
-/// information about subviews. Note that [`.slice_inplace()`] behaves like
-/// [`.collapse_axis()`] by preserving the number of dimensions.
+/// If a range is used, the axis is preserved. If an index is used, that index
+/// is selected and the axis is removed; this selects a subview. See
+/// [*Subviews*](#subviews) for more information about subviews. Note that
+/// [`.slice_inplace()`] behaves like [`.collapse_axis()`] by preserving the
+/// number of dimensions.
 ///
 /// [`.slice()`]: #method.slice
 /// [`.slice_mut()`]: #method.slice_mut
@@ -504,7 +505,7 @@ pub type Ixs = isize;
 /// assert_eq!(d, e);
 /// assert_eq!(d.shape(), &[2, 1, 3]);
 ///
-/// // Let’s create a slice while taking a subview with
+/// // Let’s create a slice while selecting a subview with
 /// //
 /// // - Both submatrices of the greatest dimension: `..`
 /// // - The last row in each submatrix, removing that axis: `-1`
@@ -520,17 +521,29 @@ pub type Ixs = isize;
 /// ## Subviews
 ///
 /// Subview methods allow you to restrict the array view while removing one
-/// axis from the array. Subview methods include [`.index_axis()`],
-/// [`.index_axis_mut()`], [`.index_axis_move()`], and [`.collapse_axis()`]. You
-/// can also take a subview by using a single index instead of a range when
-/// slicing.
-///
-/// Subview takes two arguments: `axis` and `index`.
-///
+/// axis from the array. Methods for selecting individual subviews include
+/// [`.index_axis()`], [`.index_axis_mut()`], and [`.index_axis_move()`]. You
+/// can also select a subview by using a single index instead of a range when
+/// slicing. Some other methods, such as [`.fold_axis()`], [`.axis_iter()`],
+/// [`.axis_iter_mut()`], [`.outer_iter()`], and [`.outer_iter_mut()`] operate
+/// on all the subviews along an axis.
+///
+/// A related method is [`.collapse_axis()`], which modifies the view in the
+/// same way as [`.index_axis()`] except for removing the collapsed axis, since
+/// it operates *in place*. The length of the axis becomes 1.
+///
+/// Methods for selecting an individual subview take two arguments: `axis` and
+/// `index`.
+///
+/// [`.axis_iter()`]: #method.axis_iter
+/// [`.axis_iter_mut()`]: #method.axis_iter_mut
+/// [`.fold_axis()`]: #method.fold_axis
 /// [`.index_axis()`]: #method.index_axis
 /// [`.index_axis_mut()`]: #method.index_axis_mut
 /// [`.index_axis_move()`]: #method.index_axis_move
 /// [`.collapse_axis()`]: #method.collapse_axis
+/// [`.outer_iter()`]: #method.outer_iter
+/// [`.outer_iter_mut()`]: #method.outer_iter_mut
 ///
 /// ```
 /// #[macro_use(s)] extern crate ndarray;
@@ -574,14 +587,6 @@ pub type Ixs = isize;
 /// # }
 /// ```
 ///
-/// [`.collapse_axis()`] modifies the view in the same way as [`.index_axis()`],
-/// but since it is *in place*, it cannot remove the collapsed axis. It becomes
-/// an axis of length 1.
-///
-/// `.outer_iter()` is an iterator of every subview along the zeroth (outer)
-/// axis, while `.axis_iter()` is an iterator of every subview along a
-/// specific axis.
-///
 /// ## Arithmetic Operations
 ///
 /// Arrays support all arithmetic operations the same way: they apply elementwise.

src/slice.rs

@@ -465,12 +465,13 @@ impl_slicenextdim_larger!((), Slice);
 /// The syntax is `s![` *[ axis-slice-or-index [, axis-slice-or-index [ , ... ]
 /// ] ]* `]`, where *axis-slice-or-index* is any of the following:
 ///
-/// * *index*: an index to use for taking a subview with respect to that axis
-/// * *range*: a range with step size 1 to use for slicing that axis
-/// * *range* `;` *step*: a range with step size *step* to use for slicing that axis
-/// * *slice*: a [`Slice`] instance to use for slicing that axis
+/// * *index*: an index to use for taking a subview with respect to that axis.
+///   (The index is selected and the axis is removed.)
+/// * *range*: a range with step size 1 to use for slicing that axis.
+/// * *range* `;` *step*: a range with step size *step* to use for slicing that axis.
+/// * *slice*: a [`Slice`] instance to use for slicing that axis.
 /// * *slice* `;` *step*: a range constructed from the start and end of a [`Slice`]
-///   instance, with new step size *step*, to use for slicing that axis
+///   instance, with new step size *step*, to use for slicing that axis.
 ///
 /// [`Slice`]: struct.Slice.html
 ///