Merge branch 'docs' into release-0.2.4

src/maps.rs

@@ -1,24 +1,45 @@
+//! Provides maps to associate custom data to graph vertices and edges.
+//!
+//! [`VertexMap`] and [`EdgeMap`] provide copy-on-write, [`Vec`]-backed maps to associate data to
+//! all vertices or all edges in a graph, respectively.
+
 use std::ops::{Index, IndexMut};
 
 use crate::traits::GraphTopology;
 
+/// A map to associate custom data to graph vertices.
+///
+/// This map uses raw entity indices to associate homogenous custom data of type `T` to graph
+/// vertices. The implementation uses a [`Vec`], allocating contiguous slots for the data, which
+/// means that the provided index conversion function should map vertices to contiguous indices, or
+/// indices with relatively few gaps.
+///
+/// Data allocation happens as copy-on-write, i.e. the backing [`Vec`] is only resized if a value
+/// beyond current capacity is written, but the `default` value can transparently be read. No bound
+/// or validity checks are performed by the map on the provided vertex handles.
+///
+/// Use [`GraphTopology::vertex_map`] to obtain a `VertexMap`.
 pub struct VertexMap<V: Copy, T: Clone> {
     inner: EntityMap<V, T>,
 }
 
 impl<V: Copy, T: Clone> VertexMap<V, T> {
+    /// Creates a new map with the given `default` value, an index conversion function `to_index`,
+    /// and an initial `capacity`.
     pub fn new(default: T, to_index: fn(V) -> usize, capacity: usize) -> Self {
         Self {
             inner: EntityMap::new(default, to_index, capacity),
         }
     }
 
-    // Reads beyond 'capacity' are valid and return the default value.
+    /// Returns the total number of data entries the map can write without reallocating. Reads
+    /// beyond `capacity` are valid and return the default value.
     pub fn capacity(&self) -> usize {
         self.inner.capacity()
     }
 
     #[deprecated(since = "0.2.2", note = "use 'capacity' instead")]
+    #[allow(missing_docs)]
     pub fn len(&self) -> usize {
         self.capacity()
     }
@@ -33,6 +54,7 @@ impl<V: Copy, T: Clone> VertexMap<V, T> {
     }
 
     #[deprecated(since = "0.2.4", note = "use 'extend(graph.vertex_capacity())' instead")]
+    #[allow(missing_docs)]
     pub fn sync<G: GraphTopology<Vertex = V>>(&mut self, graph: &G) {
         self.inner.extend(graph.vertex_capacity());
     }
@@ -52,23 +74,39 @@ impl<V: Copy, T: Clone> IndexMut<V> for VertexMap<V, T> {
     }
 }
 
+/// A map to associate custom data to graph edges.
+///
+/// This map uses raw entity indices to associate homogenous custom data of type `T` to graph edges.
+/// The implementation uses a [`Vec`], allocating contiguous slots for the data, which means that
+/// the provided index conversion function should map edges to contiguous indices, or indices with
+/// relatively few gaps.
+///
+/// Data allocation happens as copy-on-write, i.e. the backing [`Vec`] is only resized if a value
+/// beyond current capacity is written, but the `default` value can transparently be read. No bound
+/// or validity checks are performed by the map on the provided edge handles.
+///
+/// Use [`GraphTopology::edge_map`] to obtain an `EdgeMap`.
 pub struct EdgeMap<E: Copy, T: Clone> {
     inner: EntityMap<E, T>,
 }
 
 impl<E: Copy, T: Clone> EdgeMap<E, T> {
+    /// Creates a new map with the given `default` value, an index conversion function `to_index`,
+    /// and an initial `capacity`.
     pub fn new(default: T, to_index: fn(E) -> usize, capacity: usize) -> Self {
         Self {
             inner: EntityMap::new(default, to_index, capacity),
         }
     }
 
-    // Reads beyond 'capacity' are valid and return the default value.
+    /// Returns the total number of data entries the map can write without reallocating. Reads
+    /// beyond `capacity` are valid and return the default value.
     pub fn capacity(&self) -> usize {
         self.inner.capacity()
     }
 
     #[deprecated(since = "0.2.2", note = "use 'capacity' instead")]
+    #[allow(missing_docs)]
     pub fn len(&self) -> usize {
         self.capacity()
     }
@@ -83,6 +121,7 @@ impl<E: Copy, T: Clone> EdgeMap<E, T> {
     }
 
     #[deprecated(since = "0.2.4", note = "use 'extend(graph.edge_capacity())' instead")]
+    #[allow(missing_docs)]
     pub fn sync<G: GraphTopology<Edge = E>>(&mut self, graph: &G) {
         self.inner.extend(graph.edge_capacity());
     }