crypto: Improve the docs a bit

matrix-sdk-android/src/main/java/org/matrix/android/sdk/internal/crypto/DefaultCryptoService.kt

@@ -867,6 +867,7 @@ internal class DefaultCryptoService @Inject constructor(
      * @param warn true to warn when some unknown devices are detected.
      */
     override fun setWarnOnUnknownDevices(warn: Boolean) {
+        // TODO this doesn't seem to be used anymore?
         warnOnUnknownDevicesRepository.setWarnOnUnknownDevices(warn)
     }
 

matrix-sdk-android/src/main/java/org/matrix/android/sdk/internal/crypto/OlmMachine.kt

@@ -175,7 +175,7 @@ internal class OlmMachine(user_id: String, device_id: String, path: File, device
      *
      * After the request was sent out and a successful response was received
      * the response body should be passed back to the state machine using the
-     * mark_request_as_sent method.
+     * markRequestAsSent() method.
      *
      * @return the list of requests that needs to be sent to the homeserver
      */
@@ -259,7 +259,7 @@ internal class OlmMachine(user_id: String, device_id: String, path: File, device
      *
      * After the request was sent out and a successful response was received
      * the response body should be passed back to the state machine using the
-     * mark_request_as_sent() method.
+     * markRequestAsSent() method.
      *
      * This method should be called every time before a call to
      * shareRoomKey() is made.
@@ -279,7 +279,7 @@ internal class OlmMachine(user_id: String, device_id: String, path: File, device
      *
      * After the request was sent out and a successful response was received
      * the response body should be passed back to the state machine using the
-     * mark_request_as_sent() method.
+     * markRequestAsSent() method.
      *
      * This method should be called every time before a call to
      * `encrypt()` with the given `room_id` is made.

rust-sdk/src/machine.rs

@@ -432,6 +432,15 @@ impl OlmMachine {
         })
     }
 
+    /// Request or re-request a room key that was used to encrypt the given
+    /// event.
+    ///
+    /// # Arguments
+    ///
+    /// * `event` - The undecryptable event that we would wish to request a room
+    /// key for.
+    ///
+    /// * `room_id` - The id of the room the event was sent to.
     pub fn request_room_key(
         &self,
         event: &str,