From 07807974f79e37b349cc85c95b4ae15543838030 Mon Sep 17 00:00:00 2001
From: Devin Ragotzy <devin.ragotzy@gmail.com>
Date: Fri, 21 Aug 2020 07:39:02 -0400
Subject: [PATCH] Update readme add docs

---
 README.md  | 13 +++++++------
 src/lib.rs |  5 +++--
 2 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index b8eb1bc7..8f7685f2 100644
--- a/README.md
+++ b/README.md
@@ -16,14 +16,15 @@ pub type StateMap<T> = BTreeMap<(EventType, String), T>;
 pub type EventMap<T> = BTreeMap<EventId, T>;
 
 struct StateResolution {
-    // For now the StateResolution struct is empty. If "caching `event_map` between `resolve` calls
-    // ends up being more efficient it may have an `event_map` field.
+    // For now the StateResolution struct is empty. If "caching" `event_map`
+    // between `resolve` calls nds up being more efficient (probably not as this would eat memory)
+    // it may have an `event_map` field. The `event_map` is all the event's
+    // `StateResolution` has to know about in order to resolve state.
 }
 
 impl StateResolution {
     /// The point of this all, resolve the possibly conflicting sets of events.
     pub fn resolve(
-        &self,
         room_id: &RoomId,
         room_version: &RoomVersionId,
         state_sets: &[StateMap<EventId>],
@@ -38,9 +39,9 @@ trait StateStore {
     /// Return a single event based on the EventId.
     fn get_event(&self, event_id: &EventId) -> Result<StateEvent, String>;
 
-    // There are 3 methods that have default implementations `get_events`, `auth_event_ids` and
-    // `auth_chain_diff`. Each could be overridden if the user has an optimization with their database of
-    // choice.
+    // There are 3 methods that have default implementations `get_events`,
+    // `auth_event_ids` and `auth_chain_diff`. Each could be overridden if
+    //  the user has an optimization with their database of choice.
 }
 
 ```
diff --git a/src/lib.rs b/src/lib.rs
index cf01269a..1733859c 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -301,8 +301,9 @@ impl StateResolution {
     }
 
     /// Events are sorted from "earliest" to "latest". They are compared using
-    /// the negative power level, the origin server timestamp and incase of a
-    /// tie the `EventId`s are compared lexicographically.
+    /// the negative power level (reverse topological ordering), the
+    /// origin server timestamp and incase of a tie the `EventId`s
+    /// are compared lexicographically.
     ///
     /// The power level is negative because a higher power level is equated to an
     /// earlier (further back in time) origin server timestamp.