docs(crypto): Fill out the docs for the backup related types

Author: poljar

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;
 

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

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>,
 }