Clean up the documentation for the entity module.

lib/cretonne/src/entity/mod.rs

@@ -1,9 +1,30 @@
-//! Densely numbered entity references as mapping keys.
+//! Array-based data structures using densely numbered entity references as mapping keys.
 //!
-//! This module defines an `EntityRef` trait that should be implemented by reference types wrapping
-//! a small integer index.
+//! This module defines a number of data structures based on arrays. The arrays are not indexed by
+//! `usize` as usual, but by *entity references* which are integers wrapped in new-types. This has
+//! a couple advantages:
 //!
-//! Various data structures based on the entity references are defined in sub-modules.
+//! - Improved type safety. The various map types accept a specific key type, so there is no
+//!   confusion about the meaning of an array index, as there is with plain arrays.
+//! - Smaller indexes. The normal `usize` index is often 64 bits which is way too large for most
+//!   purposes. The entity reference types can be smaller, allowing for more compact data
+//!   structures.
+//!
+//! The `EntityRef` trait should be implemented by types to be used as indexed. The `entity_impl!`
+//! macro provides convenient defaults for types wrapping `u32` which is common.
+//!
+//! - [`PrimaryMap`](struct.PrimaryMap.html) is used to keep track of a vector of entities,
+//!   assigning a unique entity reference to each.
+//! - [`EntityMap`](struct.EntityMap.html) is used to associate secondary information to an entity.
+//!   The map is implemented as a simple vector, so it does not keep track of which entities have
+//!   been inserted. Instead, any unknown entities map to the default value.
+//! - [`SparseMap`](struct.SparseMap.html) is used to associate secondary information to a small
+//!   number of entities. It tracks accurately which entities have been inserted. This is a
+//!   specialized data structure which can use a lot of memory, so read the documentation before
+//!   using it.
+//! - [`EntityList`](struct.EntityList.html) is a compact representation of lists of entity
+//!   references allocated from an associated memory pool. It has a much smaller footprint than
+//!   `Vec`.
 
 mod keys;
 mod list;