add some minimal documentation

Author: nikomatsakis

src/lib.rs

@@ -8,6 +8,11 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! An implementation of union-find and (optionally)
+//! congruence-closure. See the `unify` and `cc` modules for more
+//! details. Note that congruence-closure requires you to opt-in to
+//! the feature "congruence-closure".
+
 // The CC code uses `impl Trait`
 #![cfg_attr(feature = "congruence-closure", feature(conservative_impl_trait))]
 #![cfg_attr(feature = "bench", feature(test))]

src/snapshot_vec.rs

@@ -18,6 +18,7 @@
 //! ensure that any changes you make this with this pointer are rolled back, you must invoke
 //! `record` to record any changes you make and also supplying a delegate capable of reversing
 //! those changes.
+
 use self::UndoLog::*;
 
 use std::mem;

src/unify/mod.rs

@@ -8,6 +8,25 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Union-find implementation. The main type is `UnificationTable`.
+//!
+//! You can define your own type for the *keys* in the table, but you
+//! must implement `UnifyKey` for that type. The assumption is that
+//! keys will be newtyped integers, hence we require that they
+//! implement `Copy`.
+//!
+//! Keys can have values associated with them. The assumption is that
+//! these values are cheaply cloneable (ideally, `Copy`), and some of
+//! the interfaces are oriented around that assumption. If you just
+//! want the classical "union-find" algorithm where you group things
+//! into sets, use the `Value` type of `()`.
+//!
+//! When you have keys with non-trivial values, you must also define
+//! how those values can be merged. If this merging is infallible, you
+//! should implement the `InfallibleUnifyValue` trait, which unlocks
+//! various more ergonomic methods (e.g., `union()` in place of
+//! `unify_var_var()`).
+
 use std::marker;
 use std::fmt::Debug;
 use std::marker::PhantomData;