add database doc comment and change insert -> add

src/db.rs

@@ -1,4 +1,9 @@
-// Key-value store using sled.
+//! Key-value store using the sled database. The database stores peer and
+//! post-related data retrieved via an sbot connection. It also stores data
+//! generated by the user through the lykin web-interface, such as whether
+//! a post has been read or not. Methods are exposed for convenient
+//! interaction with the database, such as adding inserting and returning
+//! posts.
 
 use std::{
     fmt,
@@ -10,7 +15,7 @@ use log::{debug, info};
 use serde::{Deserialize, Serialize};
 use sled::{Batch, Db, IVec, Result, Tree};
 
-// The latest sequence number and name of a Scuttlebutt peer.
+/// The latest sequence number of a Scuttlebutt peer.
 #[derive(Debug, Deserialize, Serialize)]
 pub struct Peer {
     pub latest_sequence: u64,
@@ -18,7 +23,7 @@ pub struct Peer {
     //pub posts: u16,
 }
 
-// The text and metadata of a Scuttlebutt root post.
+/// The text and metadata of a Scuttlebutt root post.
 #[derive(Debug, Deserialize, Serialize)]
 pub struct Post {
     pub key: String,
@@ -28,6 +33,8 @@ pub struct Post {
     pub read: bool,
 }
 
+/// Convenience type which facilitates converting an IVec into a String.
+/// The IVec type is returned when getting a value from the sled database.
 #[derive(Debug, Clone, PartialEq, Eq)]
 struct IVecString {
     pub bytes: IVec,
@@ -49,6 +56,7 @@ impl From<IVec> for IVecString {
     }
 }
 
+/// An instance of the key-value database and relevant trees.
 #[derive(Clone)]
 pub struct Database {
     /// Stores the sled database instance.
@@ -60,6 +68,8 @@ pub struct Database {
 }
 
 impl Database {
+    /// Initialise the database by opening the database file, loading the
+    /// peers and posts trees and returning an instantiated Database struct.
     pub fn init(path: &Path) -> Self {
         // Open the database at the given path.
         // The database will be created if it does not yet exist.
@@ -82,14 +92,20 @@ impl Database {
         }
     }
 
+    /// Add a peer to the database by inserting the public key into the peer
+    /// tree.
     pub fn add_peer(&self, public_key: &str) -> Result<Option<IVec>> {
         self.peer_tree.insert(&public_key, vec![0])
     }
 
+    /// Remove a peer from the database, as represented by the given public
+    /// key.
     pub fn remove_peer(&self, public_key: &str) -> Result<Option<IVec>> {
         self.peer_tree.remove(&public_key)
     }
 
+    /// Get a list of all peers in the peer tree. The public key of each peer
+    /// is returned.
     pub fn get_peers(&self) -> Vec<String> {
         self.peer_tree
             .iter()
@@ -99,14 +115,24 @@ impl Database {
             .collect()
     }
 
-    pub fn insert_post(&self, public_key: &str, post: Post) -> Result<Option<IVec>> {
+    /// Add a post to the database by inserting an instance of the Post struct
+    /// into the post tree. The key of the entry is formed by concatenating
+    /// the public key of the peer who authored the post and the key of the
+    /// post itself, separated by an underscore. The Post is serialized as
+    /// bincode before the database entry is inserted.
+    pub fn add_post(&self, public_key: &str, post: Post) -> Result<Option<IVec>> {
         let post_key = format!("{}_{}", public_key, post.key);
         let post_bytes = bincode::serialize(&post).unwrap();
 
         self.post_tree.insert(post_key.as_bytes(), post_bytes)
     }
 
-    pub fn insert_post_batch(&self, public_key: &str, posts: Vec<Post>) -> Result<()> {
+    /// Add a batch of posts to the database by inserting a vector of instances
+    /// of the Post struct into the post tree. The key of each entry is formed
+    /// by concatenating the public key of the peer who authored the post and
+    /// the key of the post itself, separated by an underscore. Each Post is
+    /// serialized as bincode before the database entry is inserted.
+    pub fn add_post_batch(&self, public_key: &str, posts: Vec<Post>) -> Result<()> {
         let mut post_batch = Batch::default();
 
         for post in posts {
@@ -119,6 +145,9 @@ impl Database {
         self.post_tree.apply_batch(post_batch)
     }
 
+    /// Get a list of all posts in the post tree authored by the given public
+    /// key. The byte value for each matching entry is deserialized from
+    /// bincode into an instance of the Post struct.
     pub fn get_posts(&self, public_key: &str) -> Result<Vec<Post>> {
         let mut posts = Vec::new();
 
@@ -130,6 +159,10 @@ impl Database {
         Ok(posts)
     }
 
+    /// Get a single post from the post tree, authored by the given public key
+    /// and defined by the given message ID. The byte value for the matching
+    /// entry, if found, is deserialized from bincode into an instance of the
+    /// Post struct.
     pub fn get_post(&self, public_key: &str, msg_id: &str) -> Result<Option<Post>> {
         let post_key = format!("{}_{}", public_key, msg_id);