From 670e212d9be2c4e8cb0641bbac0f877ec081a131 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Damir=20Jeli=C4=87?= <poljar@termina.org.uk>
Date: Mon, 15 Nov 2021 16:04:52 +0100
Subject: [PATCH] docs(crypto): Fill out the docs for the backup related types

---
 crates/matrix-sdk-crypto/src/backups/mod.rs |  2 +-
 crates/matrix-sdk-crypto/src/machine.rs     |  8 ++++++--
 crates/matrix-sdk-crypto/src/requests.rs    | 11 ++++++-----
 3 files changed, 13 insertions(+), 8 deletions(-)

diff --git a/crates/matrix-sdk-crypto/src/backups/mod.rs b/crates/matrix-sdk-crypto/src/backups/mod.rs
index b9fc0d721..bdfe26773 100644
--- a/crates/matrix-sdk-crypto/src/backups/mod.rs
+++ b/crates/matrix-sdk-crypto/src/backups/mod.rs
@@ -232,7 +232,7 @@ impl BackupMachine {
     }
 
     /// Encrypt a batch of room keys and return a request that needs to be sent
-    /// out to backup room keys.
+    /// out to backup the room keys.
     pub async fn backup(&self) -> Result<Option<OutgoingRequest>, CryptoStoreError> {
         let mut request = self.pending_backup.write().await;
 
diff --git a/crates/matrix-sdk-crypto/src/machine.rs b/crates/matrix-sdk-crypto/src/machine.rs
index dbdd88560..7064082ad 100644
--- a/crates/matrix-sdk-crypto/src/machine.rs
+++ b/crates/matrix-sdk-crypto/src/machine.rs
@@ -1502,7 +1502,8 @@ impl OlmMachine {
         Ok(())
     }
 
-    /// TODO
+    /// Sign the given message using our device key and if available cross
+    /// signing master key.
     pub async fn sign(&self, message: &str) -> BTreeMap<UserId, BTreeMap<DeviceKeyId, String>> {
         let mut signatures: BTreeMap<_, BTreeMap<_, _>> = BTreeMap::new();
 
@@ -1515,7 +1516,10 @@ impl OlmMachine {
         signatures
     }
 
-    /// TODO
+    /// Get a reference to the backup related state machine.
+    ///
+    /// This state machine can be used to incrementally backup all room keys to
+    /// the server.
     #[cfg(feature = "backups_v1")]
     pub fn backup_machine(&self) -> &BackupMachine {
         &self.backup_machine
diff --git a/crates/matrix-sdk-crypto/src/requests.rs b/crates/matrix-sdk-crypto/src/requests.rs
index a3b64814c..0507a391e 100644
--- a/crates/matrix-sdk-crypto/src/requests.rs
+++ b/crates/matrix-sdk-crypto/src/requests.rs
@@ -198,7 +198,7 @@ pub enum OutgoingRequests {
     /// A room message request, usually for sending in-room interactive
     /// verification events.
     RoomMessage(RoomMessageRequest),
-    /// TODO
+    /// A request that will back up a batch of room keys to the server.
     KeysBackup(KeysBackupRequest),
 }
 
@@ -287,7 +287,7 @@ pub enum IncomingResponse<'a> {
     SignatureUpload(&'a SignatureUploadResponse),
     /// A room message response, usually for interactive verifications.
     RoomMessage(&'a RoomMessageResponse),
-    /// TODO
+    /// Response for the server-side room key backup request.
     KeysBackup(&'a KeysBackupResponse),
 }
 
@@ -373,12 +373,13 @@ pub struct RoomMessageRequest {
     pub content: AnyMessageEventContent,
 }
 
-/// TODO
+/// A request that will back up a batch of room keys to the server.
 #[derive(Clone, Debug)]
 pub struct KeysBackupRequest {
-    /// TODO
+    /// The backup version that these room keys should be part of.
     pub version: String,
-    /// TODO
+    /// The map from room id to a backed up room key that we're going to upload
+    /// to the server.
     pub rooms: BTreeMap<RoomId, RoomKeyBackup>,
 }