Add some documentation

Author: laurmaedje

src/cache.rs

@@ -14,19 +14,21 @@ thread_local! {
     static CACHE: RefCell<Cache> = RefCell::new(Cache::default());
 }
 
-/// Configure the caching behaviour.
+/// Configure the caching and eviction behaviour.
 pub fn config(config: Config) {
     CACHE.with(|cache| cache.borrow_mut().config = config);
 }
 
-/// Configuration for caching behaviour.
+/// Configuration for caching and eviction behaviour.
 pub struct Config {
     max_age: u32,
 }
 
 impl Config {
     /// The maximum number of evictions an entry can survive without having been
     /// used in between.
+    ///
+    /// Default: 5
     pub fn max_age(mut self, age: u32) -> Self {
         self.max_age = age;
         self
@@ -40,6 +42,10 @@ impl Default for Config {
 }
 
 /// Evict cache entries that haven't been used in a while.
+///
+/// The eviction behaviour can be customized with the [`config`] function.
+/// Currently, comemo does not evict the cache automatically (this might
+/// change in the future).
 pub fn evict() {
     CACHE.with(|cache| {
         let mut cache = cache.borrow_mut();

src/lib.rs

@@ -1,4 +1,20 @@
-//! Tracked memoization.
+/*!
+Memoization on steroids.
+
+A _memoized_ function caches its return values so that it only needs to be
+executed once per set of unique arguments.
+While this only works for _pure_ functions (functions that don't have side
+effects), it can improve performance in many computations.
+
+However, memoization is not a silver bullet.
+In many cases, the cache hit rate isn't all that great because arguments are
+ever so slightly different.
+This is where comemo comes into play:
+It let's you reuse a function's output even when called with
+_different_ arguments as long as the difference is not observed by the function.
+It achieves this by carefully tracking which parts of an argument were actually
+accessed during the invocation of a memoized function.
+*/
 
 mod cache;
 mod constraint;

src/prehashed.rs

@@ -19,7 +19,7 @@ use siphasher::sip128::{Hasher128, SipHasher};
 /// a == b -> hash(a) == hash(b)
 /// ```
 /// The inverse implication does not follow from this immediately. However,
-/// _comemo_ uses high-quality 128 bit hashes in all places. This reduces the
+/// comemo uses high-quality 128 bit hashes in all places. This reduces the
 /// risk of a hash collision to an absolute minimum. Therefore, this trait
 /// additionally provides `PartialEq` and `Eq` implementations that compare by
 /// hash instead of by value.