From 78fdd3d5925030ccc4508f7ea038048c612df4e9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Damir=20Jeli=C4=87?= <poljar@termina.org.uk>
Date: Thu, 16 Apr 2020 11:06:51 +0200
Subject: [PATCH] crypto: Document the methods in our cryptostore trait.

---
 src/crypto/store/memorystore.rs |  4 +-
 src/crypto/store/mod.rs         | 68 ++++++++++++++++++++++++++++++++-
 src/crypto/store/sqlite.rs      |  4 +-
 3 files changed, 70 insertions(+), 6 deletions(-)

diff --git a/src/crypto/store/memorystore.rs b/src/crypto/store/memorystore.rs
index 7536597c..0e844177 100644
--- a/src/crypto/store/memorystore.rs
+++ b/src/crypto/store/memorystore.rs
@@ -21,7 +21,7 @@ use tokio::sync::Mutex;
 use super::{Account, CryptoStore, InboundGroupSession, Result, Session};
 use crate::crypto::device::Device;
 use crate::crypto::memory_stores::{DeviceStore, GroupSessionStore, SessionStore, UserDevices};
-use crate::identifiers::{RoomId, UserId};
+use crate::identifiers::{DeviceId, RoomId, UserId};
 
 #[derive(Debug)]
 pub struct MemoryStore {
@@ -84,7 +84,7 @@ impl CryptoStore for MemoryStore {
         Ok(self.tracked_users.insert(user.clone()))
     }
 
-    async fn get_device(&self, user_id: &UserId, device_id: &str) -> Result<Option<Device>> {
+    async fn get_device(&self, user_id: &UserId, device_id: &DeviceId) -> Result<Option<Device>> {
         Ok(self.devices.get(user_id, device_id))
     }
 
diff --git a/src/crypto/store/mod.rs b/src/crypto/store/mod.rs
index f1ff0ffd..7181aff1 100644
--- a/src/crypto/store/mod.rs
+++ b/src/crypto/store/mod.rs
@@ -26,7 +26,7 @@ use tokio::sync::Mutex;
 use super::device::Device;
 use super::memory_stores::UserDevices;
 use super::olm::{Account, InboundGroupSession, Session};
-use crate::identifiers::{RoomId, UserId};
+use crate::identifiers::{DeviceId, RoomId, UserId};
 use olm_rs::errors::{OlmAccountError, OlmGroupSessionError, OlmSessionError};
 
 pub mod memorystore;
@@ -65,13 +65,48 @@ pub type Result<T> = std::result::Result<T, CryptoStoreError>;
 
 #[async_trait]
 pub trait CryptoStore: Debug + Send + Sync {
+    /// Load an account that was previously stored.
     async fn load_account(&mut self) -> Result<Option<Account>>;
+
+    /// Save the given account in the store.
+    ///
+    /// # Arguments
+    ///
+    /// * `account` - The account that should be stored.
     async fn save_account(&mut self, account: Account) -> Result<()>;
 
+    /// Save the given session in the store.
+    ///
+    /// # Arguments
+    ///
+    /// * `session` - The session that should be stored.
     async fn save_session(&mut self, session: Session) -> Result<()>;
+
+    /// Get all the sessions that belong to the given sender key.
+    ///
+    /// # Arguments
+    ///
+    /// * `sender_key` - The sender key that was used to establish the sessions.
     async fn get_sessions(&mut self, sender_key: &str) -> Result<Option<Arc<Mutex<Vec<Session>>>>>;
 
+    /// Save the given inbound group session in the store.
+    ///
+    /// If the session wasn't already in the store true is returned, false
+    /// otherwise.
+    ///
+    /// # Arguments
+    ///
+    /// * `session` - The session that should be stored.
     async fn save_inbound_group_session(&mut self, session: InboundGroupSession) -> Result<bool>;
+
+    /// Get the inbound group session from our store.
+    ///
+    /// # Arguments
+    /// * `room_id` - The room id of the room that the session belongs to.
+    ///
+    /// * `sender_key` - The sender key that sent us the session.
+    ///
+    /// * `session_id` - The unique id of the session.
     async fn get_inbound_group_session(
         &mut self,
         room_id: &RoomId,
@@ -79,10 +114,39 @@ pub trait CryptoStore: Debug + Send + Sync {
         session_id: &str,
     ) -> Result<Option<InboundGroupSession>>;
 
+    /// Get the set of tracked users.
     fn tracked_users(&self) -> &HashSet<UserId>;
+
+    /// Add an user for tracking.
+    ///
+    /// Returns true if the user wasn't already tracked, false otherwise.
+    ///
+    /// # Arguments
+    ///
+    /// * `user` - The user that should be marked as tracked.
     async fn add_user_for_tracking(&mut self, user: &UserId) -> Result<bool>;
 
+    /// Save the given device in the store.
+    ///
+    /// # Arguments
+    ///
+    /// * `device` - The device that should be stored.
     async fn save_device(&self, device: Device) -> Result<()>;
-    async fn get_device(&self, user_id: &UserId, device_id: &str) -> Result<Option<Device>>;
+
+    /// Get the device for the given user with the given device id.
+    ///
+    /// # Arguments
+    ///
+    /// * `user_id` - The user that the device belongs to.
+    ///
+    /// * `device_id` - The unique id of the device.
+    async fn get_device(&self, user_id: &UserId, device_id: &DeviceId) -> Result<Option<Device>>;
+
+    /// Get all the devices of the given user.
+    ///
+    ///
+    /// # Arguments
+    ///
+    /// * `user_id` - The user for which we should get all the devices.
     async fn get_user_devices(&self, user_id: &UserId) -> Result<UserDevices>;
 }
diff --git a/src/crypto/store/sqlite.rs b/src/crypto/store/sqlite.rs
index 98846790..8c58cb0d 100644
--- a/src/crypto/store/sqlite.rs
+++ b/src/crypto/store/sqlite.rs
@@ -30,7 +30,7 @@ use zeroize::Zeroizing;
 use super::{Account, CryptoStore, CryptoStoreError, InboundGroupSession, Result, Session};
 use crate::crypto::device::Device;
 use crate::crypto::memory_stores::{GroupSessionStore, SessionStore, UserDevices};
-use crate::identifiers::{RoomId, UserId};
+use crate::identifiers::{DeviceId, RoomId, UserId};
 
 pub struct SqliteStore {
     user_id: Arc<String>,
@@ -402,7 +402,7 @@ impl CryptoStore for SqliteStore {
         Ok(self.tracked_users.insert(user.clone()))
     }
 
-    async fn get_device(&self, _user_id: &UserId, _device_id: &str) -> Result<Option<Device>> {
+    async fn get_device(&self, _user_id: &UserId, _device_id: &DeviceId) -> Result<Option<Device>> {
         todo!()
     }