Add documentation for maps module

src/maps.rs

@@ -1,19 +1,39 @@
+//! 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()
     }
@@ -42,18 +62,33 @@ 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()
     }