From 95c87089957b9a98303ba4f2f8d49e5eea35f285 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Damir=20Jeli=C4=87?= <poljar@termina.org.uk>
Date: Mon, 24 Aug 2020 14:49:57 +0200
Subject: [PATCH] crypto: Document and rename the mark_requests_as_sent()
 method.

---
 matrix_sdk_base/src/client.rs                 | 20 ++++++++++++++---
 matrix_sdk_crypto/src/machine.rs              | 22 +++++++++++++++----
 matrix_sdk_crypto/src/verification/machine.rs |  4 ++--
 3 files changed, 37 insertions(+), 9 deletions(-)

diff --git a/matrix_sdk_base/src/client.rs b/matrix_sdk_base/src/client.rs
index d057bd78..86724984 100644
--- a/matrix_sdk_base/src/client.rs
+++ b/matrix_sdk_base/src/client.rs
@@ -1244,7 +1244,13 @@ impl BaseClient {
         }
     }
 
-    /// Get the list of outgoing requests that need to be sent out.
+    /// Get the outgoing requests that need to be sent out.
+    ///
+    /// This returns a list of `OutGoingRequest`, those requests need to be sent
+    /// out to the server and the responses need to be passed back to the state
+    /// machine using [`mark_request_as_sent`].
+    ///
+    /// [`mark_request_as_sent`]: #method.mark_request_as_sent
     #[cfg(feature = "encryption")]
     #[cfg_attr(feature = "docs", doc(cfg(encryption)))]
     pub async fn outgoing_requests(&self) -> Vec<OutgoingRequest> {
@@ -1256,7 +1262,15 @@ impl BaseClient {
         }
     }
 
-    /// Get the list of outgoing requests that need to be sent out.
+    /// Mark the request with the given request id as sent.
+    ///
+    /// # Arguments
+    ///
+    /// * `request_id` - The unique id of the request that was sent out. This is
+    /// needed to couple the response with the now sent out request.
+    ///
+    /// * `response` - The response that was received from the server after the
+    /// outgoing request was sent out.
     #[cfg(feature = "encryption")]
     #[cfg_attr(feature = "docs", doc(cfg(encryption)))]
     pub async fn mark_request_as_sent<'a>(
@@ -1267,7 +1281,7 @@ impl BaseClient {
         let olm = self.olm.lock().await;
 
         match &*olm {
-            Some(o) => Ok(o.mark_requests_as_sent(request_id, response).await?),
+            Some(o) => Ok(o.mark_request_as_sent(request_id, response).await?),
             None => Ok(()),
         }
     }
diff --git a/matrix_sdk_crypto/src/machine.rs b/matrix_sdk_crypto/src/machine.rs
index 10e785d7..eb27976c 100644
--- a/matrix_sdk_crypto/src/machine.rs
+++ b/matrix_sdk_crypto/src/machine.rs
@@ -218,6 +218,12 @@ impl OlmMachine {
     }
 
     /// Get the outgoing requests that need to be sent out.
+    ///
+    /// This returns a list of `OutGoingRequest`, those requests need to be sent
+    /// out to the server and the responses need to be passed back to the state
+    /// machine using [`mark_request_as_sent`].
+    ///
+    /// [`mark_request_as_sent`]: #method.mark_request_as_sent
     pub async fn outgoing_requests(&self) -> Vec<OutgoingRequest> {
         let mut requests = Vec::new();
 
@@ -241,7 +247,15 @@ impl OlmMachine {
     }
 
     /// Mark the request with the given request id as sent.
-    pub async fn mark_requests_as_sent<'a>(
+    ///
+    /// # Arguments
+    ///
+    /// * `request_id` - The unique id of the request that was sent out. This is
+    /// needed to couple the response with the now sent out request.
+    ///
+    /// * `response` - The response that was received from the server after the
+    /// outgoing request was sent out.
+    pub async fn mark_request_as_sent<'a>(
         &self,
         request_id: &Uuid,
         response: impl Into<IncomingResponse<'a>>,
@@ -355,14 +369,14 @@ impl OlmMachine {
     /// This should be called every time a group session needs to be shared.
     ///
     /// The response of a successful key claiming requests needs to be passed to
-    /// the `OlmMachine` with the [`mark_requests_as_sent`].
+    /// the `OlmMachine` with the [`mark_request_as_sent`].
     ///
     /// # Arguments
     ///
     /// `users` - The list of users that we should check if we lack a session
     /// with one of their devices.
     ///
-    /// [`mark_requests_as_sent`]: #method.mark_requests_as_sent
+    /// [`mark_request_as_sent`]: #method.mark_request_as_sent
     pub async fn get_missing_sessions(
         &self,
         users: impl Iterator<Item = &UserId>,
@@ -1242,7 +1256,7 @@ impl OlmMachine {
 
     /// Mark an outgoing to-device requests as sent.
     fn mark_to_device_request_as_sent(&self, request_id: &Uuid) {
-        self.verification_machine.mark_requests_as_sent(request_id);
+        self.verification_machine.mark_request_as_sent(request_id);
     }
 
     /// Get a `Sas` verification object with the given flow id.
diff --git a/matrix_sdk_crypto/src/verification/machine.rs b/matrix_sdk_crypto/src/verification/machine.rs
index f6aebff8..898c5830 100644
--- a/matrix_sdk_crypto/src/verification/machine.rs
+++ b/matrix_sdk_crypto/src/verification/machine.rs
@@ -98,7 +98,7 @@ impl VerificationMachine {
         }
     }
 
-    pub fn mark_requests_as_sent(&self, uuid: &Uuid) {
+    pub fn mark_request_as_sent(&self, uuid: &Uuid) {
         self.outgoing_to_device_messages.remove(uuid);
     }
 
@@ -321,7 +321,7 @@ mod test {
 
         let mut event = wrap_any_to_device_content(alice.user_id(), get_content_from_request(r));
         drop(request);
-        alice_machine.mark_requests_as_sent(&txn_id);
+        alice_machine.mark_request_as_sent(&txn_id);
 
         assert!(bob.receive_event(&mut event).is_none());