diff --git a/vwowrla.core/src/vwowrla/core/encounters/analysis.clj b/vwowrla.core/src/vwowrla/core/encounters/analysis.clj
index 60e2918..1b1e625 100644
--- a/vwowrla.core/src/vwowrla/core/encounters/analysis.clj
+++ b/vwowrla.core/src/vwowrla/core/encounters/analysis.clj
@@ -10,6 +10,7 @@
     vwowrla.core.utils))
 
 (s/defn active-encounter? :- s/Bool
+  "returns true if the log analysis data contains an active encounter"
   [data :- RaidAnalysis]
   (not (nil? (:active-encounter data))))
 
@@ -51,7 +52,7 @@
   (get-in encounter [:entities entity-name :last-activity-at]))
 
 (s/defn get-entity-alive-time :- Long
-  "returns the number of milliseconds of the encounter that the entity was alive for"
+  "returns the total time that the given entity was alive for in the encounter (time in milliseconds)"
   [{:keys [deaths resurrections]}              :- Entity
    {:keys [started-at ended-at] :as encounter} :- Encounter]
   (if (and (= 0 (count deaths))
diff --git a/vwowrla.core/src/vwowrla/core/encounters/core.clj b/vwowrla.core/src/vwowrla/core/encounters/core.clj
index 0e0fc54..f91fe9c 100644
--- a/vwowrla.core/src/vwowrla/core/encounters/core.clj
+++ b/vwowrla.core/src/vwowrla/core/encounters/core.clj
@@ -13,7 +13,7 @@
 
 (s/defn find-defined-encounter-name :- (s/maybe s/Str)
   "returns the name of a defined encounter which includes the given entity in it's
-   list of trigger entities. returns nil if there is no encounter which includes the
+   list of encounter entities. returns nil if there is no encounter which includes the
    given entity"
   [entity-name :- (s/maybe s/Str)]
   (->> defined-encounters
@@ -42,16 +42,16 @@
 
 (s/defn update-active-encounter :- RaidAnalysis
   "updates the active encounter using function f which will take the current active
-   encounter and any supplied args, returning a new active encounter which is
-   'updated' in the original full parsed data and then finally returned."
+   encounter and any supplied args. f should return a new encounter.
+   returns the log analysis data with the modified active encounter."
   [data :- RaidAnalysis
    f & args]
   (apply update-in data [:active-encounter] f args))
 
 (s/defn update-all-entities :- Encounter
   "updates all entities in the encounter using function f which takes the current
-   entity and any supplied args, returning a new entity which is 'updated' in the
-   original encounter. returns the encounter with the modified entity data."
+   entity and any supplied args. f should return a new/updated entity.
+   returns the encounter with the modified entity data."
   [encounter :- Encounter
    f & args]
   (reduce
@@ -69,20 +69,21 @@
    f & args]
   (update-active-encounter data #(update-all-entities % f args)))
 
-  "updates an entity in the full parsed data's active encounter using function f
-   which takes the current entity and any supplied args, returning the new entity
-   which is 'updated' in the active encounter. returns the updated full parsed data."
 (s/defn update-entity :- Encounter
+  "updates an entity (specified by name) in the encounter using function f which
+   takes the current entity (or nil if no such entity exists in the encounter) and
+   any supplied args. f should return a new/updated entity.
+   returns the encounter with the updated entity."
   [encounter   :- Encounter
    entity-name :- s/Str
    f & args]
   (apply update-in encounter [:entities entity-name] f args))
 
-  "updates a specific field within an entity pointed to by ks in the full parsed
-   data's active encounter using function f which takes the current entity and any
-   supplied args, returning the new entity which is 'updated' in the active encounter.
-   returns the updated full parsed data."
 (s/defn update-entity-field :- Encounter
+  "updates a specific field (pointed to by ks) within an entity (specified by name)
+   in the encounter using function f which takes the value of the entity field
+   specified and any supplied args. f should return the new value for that field.
+   returns the encounter with the updated entity."
   [encounter   :- Encounter
    entity-name :- s/Str
    ks f & args]
diff --git a/vwowrla.core/src/vwowrla/core/encounters/detection.clj b/vwowrla.core/src/vwowrla/core/encounters/detection.clj
index f49fe7f..5bf4574 100644
--- a/vwowrla.core/src/vwowrla/core/encounters/detection.clj
+++ b/vwowrla.core/src/vwowrla/core/encounters/detection.clj
@@ -55,9 +55,9 @@
        (boolean)))
 
 (s/defn detect-encounter-triggered :- (s/maybe s/Str)
-  "determines if the parsed combat log line is for an event involving any specific encounter entities which
-   should cause an encounter to begin, returning the name of the encounter if it should begin, or nil if no
-   encounter begin was detected"
+  "determines if the given combat event should trigger the beginning of an encounter or not.
+   returns the name of the encounter that should begin or nil if no encounter trigger was
+   detected"
   [{:keys [target-name source-name damage aura-name type skill] :as event} :- CombatEvent
    data :- RaidAnalysis]
   (if-let [encounter-name (or (find-defined-encounter-name target-name)
@@ -89,10 +89,11 @@
           encounter-name)))))
 
 (s/defn detect-encounter-end :- (s/maybe s/Keyword)
-  "determines if the currently active encounter should end based on the active encounter parsed data.
-   returns :killed if the encounter should end due to a successful kill, :wipe-or-timeout if the
-   encounter was found to be over due to a raid wipe or other non-activity timeout, or nil if the
-   active encounter is not over yet."
+  "determines if the encounter should end based on the given combat event and the current state
+   of the encounter.
+   returns :killed for a successful encounter end (all encounter entities killed).
+   returns :wipe-or-timeout if there was a wipe or other encounter entity activity timeout.
+   returns nil if the encounter is not over yet."
   [{:keys [^Date timestamp]} :- CombatEvent
    encounter                 :- Encounter]
   (let [trigger-entites (:trigger-entities encounter)]