Put COO, CSR, SparsityPattern and related types in their own modules

This mimics how std does it, e.g. std::vec::Vec. This avoids potential
problems down the road, where adding more types might clutter the
API interface and generated documentation.

nalgebra-sparse/src/coo.rs

@@ -1,3 +1,5 @@
+//! An implementation of the COO sparse matrix format.
+
 use crate::SparseFormatError;
 use nalgebra::{ClosedAdd, DMatrix, Scalar};
 use num_traits::Zero;
@@ -24,7 +26,7 @@ use num_traits::Zero;
 /// -------
 ///
 /// ```rust
-/// # use nalgebra_sparse::CooMatrix;
+/// # use nalgebra_sparse::coo::CooMatrix;
 /// // Create a zero matrix
 /// let mut coo = CooMatrix::new(4, 4);
 /// // Or initialize it with a set of triplets
@@ -165,7 +167,7 @@ where
     /// --------
     ///
     /// ```
-    /// # use nalgebra_sparse::CooMatrix;
+    /// # use nalgebra_sparse::coo::CooMatrix;
     /// let row_indices = vec![0, 1];
     /// let col_indices = vec![1, 2];
     /// let values = vec![1.0, 2.0];

nalgebra-sparse/src/csr.rs

@@ -1,5 +1,7 @@
-use crate::{SparsityPattern, SparseFormatError, SparsityPatternFormatError, SparseFormatErrorKind};
-use crate::iter::SparsityPatternIter;
+//! An implementation of the CSR sparse matrix format.
+
+use crate::{SparseFormatError, SparseFormatErrorKind};
+use crate::pattern::{SparsityPattern, SparsityPatternFormatError, SparsityPatternIter};
 
 use std::sync::Arc;
 use std::slice::{IterMut, Iter};
@@ -124,7 +126,7 @@ impl<T> CsrMatrix<T> {
     /// Examples
     /// --------
     /// ```
-    /// # use nalgebra_sparse::CsrMatrix;
+    /// # use nalgebra_sparse::csr::CsrMatrix;
     /// let row_offsets = vec![0, 2, 3, 4];
     /// let col_indices = vec![0, 2, 1, 0];
     /// let values = vec![1, 2, 3, 4];
@@ -148,7 +150,7 @@ impl<T> CsrMatrix<T> {
     /// Examples
     /// --------
     /// ```
-    /// # use nalgebra_sparse::CsrMatrix;
+    /// # use nalgebra_sparse::csr::CsrMatrix;
     /// # let row_offsets = vec![0, 2, 3, 4];
     /// # let col_indices = vec![0, 2, 1, 0];
     /// # let values = vec![1, 2, 3, 4];
@@ -432,6 +434,7 @@ impl<'a, T> CsrRowMut<'a, T> {
     }
 }
 
+/// Row iterator for [CsrMatrix](struct.CsrMatrix.html).
 pub struct CsrRowIter<'a, T> {
     // The index of the row that will be returned on the next
     current_row_idx: usize,
@@ -448,6 +451,7 @@ impl<'a, T> Iterator for CsrRowIter<'a, T> {
     }
 }
 
+/// Mutable row iterator for [CsrMatrix](struct.CsrMatrix.html).
 pub struct CsrRowIterMut<'a, T> {
     current_row_idx: usize,
     pattern: &'a SparsityPattern,

nalgebra-sparse/src/lib.rs

@@ -65,30 +65,11 @@
 #![deny(unused_results)]
 #![deny(missing_docs)]
 
-mod coo;
-mod csr;
-mod pattern;
-
+pub mod coo;
+pub mod csr;
+pub mod pattern;
 pub mod ops;
 
-pub use coo::CooMatrix;
-pub use csr::{CsrMatrix, CsrRow, CsrRowMut};
-pub use pattern::{SparsityPattern, SparsityPatternFormatError};
-
-/// Iterator types for matrices.
-///
-/// Most users will not need to interface with these types directly. Instead, refer to the
-/// iterator methods for the respective matrix formats.
-pub mod iter {
-    // Iterators are best implemented in the same modules as the matrices they iterate over,
-    // since they are so closely tied to their respective implementations. However,
-    // in the crate's public API we move them into a separate `iter` module in order to avoid
-    // cluttering the docs with iterator types that most users will never need to explicitly
-    // know about.
-    pub use crate::pattern::SparsityPatternIter;
-    pub use crate::csr::{CsrTripletIter, CsrTripletIterMut};
-}
-
 use std::error::Error;
 use std::fmt;
 

nalgebra-sparse/src/ops.rs

@@ -1,6 +1,6 @@
 //! Matrix operations involving sparse matrices.
 
-use crate::CooMatrix;
+use crate::coo::CooMatrix;
 use nalgebra::base::storage::{Storage, StorageMut};
 use nalgebra::{ClosedAdd, ClosedMul, Dim, Scalar, Vector};
 use num_traits::{One, Zero};

nalgebra-sparse/src/pattern.rs

@@ -1,3 +1,4 @@
+//! Sparsity patterns for CSR and CSC matrices.
 use crate::SparseFormatError;
 use std::fmt;
 use std::error::Error;
@@ -156,7 +157,7 @@ impl SparsityPattern {
     /// --------
     ///
     /// ```
-    /// # use nalgebra_sparse::{SparsityPattern};
+    /// # use nalgebra_sparse::pattern::SparsityPattern;
     /// let offsets = vec![0, 2, 3, 4];
     /// let minor_indices = vec![0, 2, 1, 0];
     /// let pattern = SparsityPattern::try_from_offsets_and_indices(3, 4, offsets, minor_indices)

nalgebra-sparse/tests/unit_tests/coo.rs

@@ -1,4 +1,5 @@
-use nalgebra_sparse::{CooMatrix, SparseFormatErrorKind};
+use nalgebra_sparse::{SparseFormatErrorKind};
+use nalgebra_sparse::coo::CooMatrix;
 use nalgebra::DMatrix;
 use crate::assert_panics;
 

nalgebra-sparse/tests/unit_tests/ops.rs

@@ -1,4 +1,4 @@
-use nalgebra_sparse::CooMatrix;
+use nalgebra_sparse::coo::CooMatrix;
 use nalgebra_sparse::ops::spmv_coo;
 use nalgebra::DVector;