Fills missing documentation and adds warn(missing_docs) (#1525)

Author: akern40

src/dimension/broadcast.rs

@@ -34,6 +34,13 @@ where
     Ok(out)
 }
 
+/// A trait to specify when one dimension is strictly larger than another.
+///
+/// Broadcasting two arrays together frequently requires typing the resultant
+/// array has having a dimensionality equal to the maximum of the two input arrays.
+/// This trait is what determines that typing.
+///
+/// For example, `Ix1: DimMax<Ix0>`, but not vice-versa.
 pub trait DimMax<Other: Dimension>
 {
     /// The resulting dimension type after broadcasting.

src/dimension/conversion.rs

@@ -42,7 +42,10 @@ macro_rules! index_item {
 /// Argument conversion a dimension.
 pub trait IntoDimension
 {
+    /// The concrete type of the resultant dimension.
     type Dim: Dimension;
+
+    /// Convert into a type that implements [`Dimension`].
     fn into_dimension(self) -> Self::Dim;
 }
 

src/dimension/remove_axis.rs

@@ -14,6 +14,7 @@ use crate::{Axis, Dim, Dimension, Ix, Ix0, Ix1};
 /// removing one axis from *Self* gives smaller dimension *Smaller*.
 pub trait RemoveAxis: Dimension
 {
+    /// Remove the specified axis from a dimension.
     fn remove_axis(&self, axis: Axis) -> Self::Smaller;
 }
 

src/lib.rs

@@ -22,6 +22,7 @@
 #![cfg_attr(not(feature = "std"), no_std)]
 // Enable the doc_cfg nightly feature for including feature gate flags in the documentation
 #![cfg_attr(docsrs, feature(doc_cfg))]
+#![warn(missing_docs)]
 
 //! The `ndarray` crate provides an *n*-dimensional container for general elements
 //! and for numerics.

src/linalg/impl_linalg.rs

@@ -164,6 +164,9 @@ pub trait Dot<Rhs>
     /// For two-dimensional arrays: a rectangular array.
     type Output;
 
+    /// Compute the dot product of two arrays.
+    ///
+    /// **Panics** if the arrays' shapes are not compatible.
     fn dot(&self, rhs: &Rhs) -> Self::Output;
 }
 

src/shape_builder.rs

@@ -96,12 +96,22 @@ impl<D> Strides<D>
 /// `Array::from_shape_vec`.
 pub trait ShapeBuilder
 {
+    /// The type that captures the built shape's dimensionality.
     type Dim: Dimension;
+
+    /// The type that captures the built shape's stride pattern.
     type Strides;
 
+    /// Turn into a contiguous-element [`Shape`].
     fn into_shape_with_order(self) -> Shape<Self::Dim>;
+
+    /// Convert into a Fortran-order (a.k.a., column-order) [`Shape`].
     fn f(self) -> Shape<Self::Dim>;
+
+    /// Set the order of the shape to either Fortran or non-Fortran.
     fn set_f(self, is_f: bool) -> Shape<Self::Dim>;
+
+    /// Set the strides of the shape.
     fn strides(self, strides: Self::Strides) -> StrideShape<Self::Dim>;
 }
 
@@ -213,7 +223,10 @@ where D: Dimension
 /// See for example [`.to_shape()`](crate::ArrayRef::to_shape).
 pub trait ShapeArg
 {
+    /// The type that captures the shape's dimensionality.
     type Dim: Dimension;
+
+    /// Convert the argument into a shape and an [`Order`].
     fn into_shape_and_order(self) -> (Self::Dim, Option<Order>);
 }
 

src/zip/ndproducer.rs

@@ -16,6 +16,7 @@ pub trait IntoNdProducer
     type Item;
     /// Dimension type of the producer
     type Dim: Dimension;
+    /// The concrete type of the producer
     type Output: NdProducer<Dim = Self::Dim, Item = Self::Item>;
     /// Convert the value into an `NdProducer`.
     fn into_producer(self) -> Self::Output;