Some comments to help explain stats_tracker

src/stats_tracker.h

@@ -4,6 +4,14 @@
 #include "event_bus.h"
 #include "hash_utils.h"
 
+// The stats_tracker is intended to keep a summary of events that have occured.
+// For each event_type it stores an event_tracker.
+// Within the event_tracker, counts are kept.  The events are partitioned
+// according to their data (an event::data_type object, which is a map of keys
+// to values).
+// The stats_tracker can be queried in various ways to get summary statistics
+// about events that have occured.
+
 class event_tracker
 {
     public:
@@ -21,6 +29,20 @@ class event_tracker
 class stats_tracker : public event_subscriber
 {
     public:
+        // count returns the number of events matching given criteria that have
+        // occured.
+        // total returns the sum of some integer-valued field across every
+        // event satisfying certain criteria.
+        // For example, count might return the number of times the avatar has
+        // taken damage, while total might return the total damage taken in all
+        // those cases.
+        // The criteria have two parts:
+        // - The event_type
+        // - An event::data_type map specifying some values that must be
+        //   matched in the events of that type.  You can provide just a subset
+        //   of the relevant keys from the event_type in your criteria.
+        // The first count overload combines these criteria into a single event
+        // object for convenience since that contains the two pieces necessary.
         int count( const cata::event & ) const;
         int count( event_type, const cata::event::data_type &criteria ) const;
         int total( event_type, const std::string &field,