Add documentation (#41)

Added documentation to lib.rs and database.rs files

src/database.rs

@@ -21,8 +21,21 @@ use std::{borrow::Cow, collections::BTreeMap, fmt};
 
 use super::StateGroupEntry;
 
-/// Fetch the entries in state_groups_state (and their prev groups) for the
-/// given `room_id` by connecting to the postgres database at `db_url`.
+/// Fetch the entries in state_groups_state (and their prev groups) for a
+/// specific room.
+///
+/// - Connects to the database
+/// - Fetches rows with group id lower than max
+/// - Recursively searches for missing predecessors and adds those
+///
+/// # Arguments
+///
+/// * `room_id`         -   The ID of the room in the database
+/// * `db_url`          -   The URL of a Postgres database. This should be of the
+///                         form: "postgresql://user:pass@domain:port/database"
+/// * `max_state_group` -   If specified, then only fetch the entries for state
+///                         groups lower than or equal to this number. (N.B. all
+///                         predecessors are also fetched)
 pub fn get_data_from_db(
     db_url: &str,
     room_id: &str,
@@ -43,6 +56,9 @@ pub fn get_data_from_db(
     // in our DB queries, so we have to fetch any missing groups explicitly.
     // Since the returned groups may themselves reference groups we don't have,
     // we need to do this recursively until we don't find any more missing.
+    //
+    // N.B. This does NOT currently fetch the deltas for the missing groups!
+    // By carefully chosen max_state_group this might cause issues...?
     loop {
         let mut missing_sgs: Vec<_> = state_group_map
             .iter()
@@ -76,13 +92,25 @@ pub fn get_data_from_db(
     state_group_map
 }
 
-/// Fetch the entries in state_groups_state (and their prev groups) for the
-/// given `room_id` by fetching all state with the given `room_id`.
+/// Fetch the entries in state_groups_state and immediate predecessors for
+/// a specific room.
+///
+/// - Fetches rows with group id lower than max
+/// - Stores the group id, predecessor id and deltas into a map
+///
+/// # Arguments
+///
+/// * `client`          -   A Postgres client to make requests with
+/// * `room_id`         -   The ID of the room in the database
+/// * `max_state_group` -   If specified, then only fetch the entries for state
+///                         groups lower than or equal to this number. (N.B. doesn't
+///                         fetch IMMEDIATE predecessors if ID is above this number)
 fn get_initial_data_from_db(
     client: &mut Client,
     room_id: &str,
     max_state_group: Option<i64>,
 ) -> BTreeMap<i64, StateGroupEntry> {
+    // Query to get id, predecessor and delta for each state group
     let sql = r#"
         SELECT m.id, prev_state_group, type, state_key, s.event_id
         FROM state_groups AS m
@@ -91,6 +119,8 @@ fn get_initial_data_from_db(
         WHERE m.room_id = $1
     "#;
 
+    // Adds additional constraint if a max_state_group has been specified
+    // Then sends query to the datatbase
     let mut rows = if let Some(s) = max_state_group {
         let params: Vec<&dyn ToSql> = vec![&room_id, &s];
         client.query_raw(format!(r"{} AND m.id <= $2", sql).as_str(), params)
@@ -99,6 +129,8 @@ fn get_initial_data_from_db(
     }
     .unwrap();
 
+    // Copy the data from the database into a map
+
     let mut state_group_map: BTreeMap<i64, StateGroupEntry> = BTreeMap::new();
 
     let pb = ProgressBar::new_spinner();
@@ -108,10 +140,13 @@ fn get_initial_data_from_db(
     pb.enable_steady_tick(100);
 
     while let Some(row) = rows.next().unwrap() {
+        // The row in the map to copy the data to
         let entry = state_group_map.entry(row.get(0)).or_default();
 
+        // Save the predecessor (this may already be there)
         entry.prev_state_group = row.get(1);
 
+        // Copy the single delta from the predecessor stored in this row
         if let Some(etype) = row.get::<_, Option<String>>(2) {
             entry.state_map.insert(
                 &etype,
@@ -129,7 +164,14 @@ fn get_initial_data_from_db(
     state_group_map
 }
 
-/// Get any missing state groups from the database
+/// Finds the predecessors of missing state groups
+///
+/// N.B. this does NOT find their deltas
+///
+/// # Arguments
+///
+/// * `client`          -   A Postgres client to make requests with
+/// * `missing_sgs`     -   An array of missing state_group ids
 fn get_missing_from_db(client: &mut Client, missing_sgs: &[i64]) -> BTreeMap<i64, StateGroupEntry> {
     let mut rows = client
         .query_raw(