From d606bd3e9fbd702bb4c7ea7eab06fa79b9b11f20 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Damir=20Jeli=C4=87?= <poljar@termina.org.uk>
Date: Wed, 5 Apr 2023 11:18:50 +0200
Subject: [PATCH] Document the new withheld content enums

---
 .../src/store/integration_tests.rs            | 26 +++++++---------
 .../src/types/events/room_key_withheld.rs     | 31 +++++++++++++++++--
 2 files changed, 41 insertions(+), 16 deletions(-)

diff --git a/crates/matrix-sdk-crypto/src/store/integration_tests.rs b/crates/matrix-sdk-crypto/src/store/integration_tests.rs
index ba39cfc3a..b148ffc68 100644
--- a/crates/matrix-sdk-crypto/src/store/integration_tests.rs
+++ b/crates/matrix-sdk-crypto/src/store/integration_tests.rs
@@ -638,16 +638,15 @@ macro_rules! cryptostore_integration_tests {
 
                 let content = RoomKeyWithheldContent::MegolmV1AesSha2(
                     MegolmV1AesSha2WithheldContent::Unverified(
-                        CommonWithheldCodeContent {
-                            room_id: room_id.to_owned(),
-                            session_id: session_id_1.into(),
-                            from_device: JsOption::Undefined,
-                            other: Default::default(),
-                            sender_key: Curve25519PublicKey::from_base64(
+                        CommonWithheldCodeContent::new(
+                            room_id.to_owned(),
+                            session_id_1.into(),
+                            Curve25519PublicKey::from_base64(
                                 "9n7mdWKOjr9c4NTlG6zV8dbFtNK79q9vZADoh7nMUwA",
                             )
                             .unwrap(),
-                        }
+                            "DEVICEID".into(),
+                        )
                         .into(),
                     ),
                 );
@@ -659,16 +658,15 @@ macro_rules! cryptostore_integration_tests {
 
                 let content = RoomKeyWithheldContent::MegolmV1AesSha2(
                     MegolmV1AesSha2WithheldContent::BlackListed(
-                        CommonWithheldCodeContent {
-                            room_id: room_id.to_owned(),
-                            session_id: session_id_2.into(),
-                            from_device: JsOption::Undefined,
-                            other: Default::default(),
-                            sender_key: Curve25519PublicKey::from_base64(
+                        CommonWithheldCodeContent::new(
+                            room_id.to_owned(),
+                            session_id_2.into(),
+                            Curve25519PublicKey::from_base64(
                                 "9n7mdWKOjr9c4NTlG6zV8dbFtNK79q9vZADoh7nMUwA",
                             )
                             .unwrap(),
-                        }
+                            "DEVICEID".into(),
+                        )
                         .into(),
                     ),
                 );
diff --git a/crates/matrix-sdk-crypto/src/types/events/room_key_withheld.rs b/crates/matrix-sdk-crypto/src/types/events/room_key_withheld.rs
index 3f79dd1b4..768cf7596 100644
--- a/crates/matrix-sdk-crypto/src/types/events/room_key_withheld.rs
+++ b/crates/matrix-sdk-crypto/src/types/events/room_key_withheld.rs
@@ -130,6 +130,7 @@ impl RoomKeyWithheldContent {
         }
     }
 
+    /// Get the withheld code of this event.
     pub fn withheld_code(&self) -> WithheldCode {
         match self {
             RoomKeyWithheldContent::MegolmV1AesSha2(c) => c.withheld_code(),
@@ -222,15 +223,23 @@ struct WithheldHelper {
     other: Value,
 }
 
+/// Content for the `m.room_key.withheld` event for the `m.megolm.v1.aes-sha2`
+/// algorithm.
 #[derive(Clone, Debug)]
 pub enum MegolmV1AesSha2WithheldContent {
+    /// The `m.blacklisted` variant of the withheld code content.
     BlackListed(Box<CommonWithheldCodeContent>),
+    /// The `m.unverified` variant of the withheld code content.
     Unverified(Box<CommonWithheldCodeContent>),
+    /// The `m.unauthorised` variant of the withheld code content.
     Unauthorised(Box<CommonWithheldCodeContent>),
+    /// The `m.unavailable` variant of the withheld code content.
     Unavailable(Box<CommonWithheldCodeContent>),
+    /// The `m.no_olm` variant of the withheld code content.
     NoOlm(Box<NoOlmWithheldContent>),
 }
 
+/// Struct for most of the withheld code content variants.
 #[derive(Clone, PartialEq, Eq, Deserialize, Serialize)]
 pub struct CommonWithheldCodeContent {
     /// The room where the key is used.
@@ -249,7 +258,25 @@ pub struct CommonWithheldCodeContent {
     pub from_device: JsOption<OwnedDeviceId>,
 
     #[serde(flatten)]
-    pub other: BTreeMap<String, Value>,
+    other: BTreeMap<String, Value>,
+}
+
+impl CommonWithheldCodeContent {
+    /// Create a new common withheld code content.
+    pub fn new(
+        room_id: OwnedRoomId,
+        session_id: String,
+        sender_key: Curve25519PublicKey,
+        device_id: OwnedDeviceId,
+    ) -> Self {
+        Self {
+            room_id,
+            session_id,
+            sender_key,
+            from_device: JsOption::Some(device_id),
+            other: Default::default(),
+        }
+    }
 }
 
 impl MegolmV1AesSha2WithheldContent {
@@ -323,7 +350,7 @@ pub struct UnknownRoomKeyWithHeld {
     pub algorithm: EventEncryptionAlgorithm,
     /// The withheld code
     pub code: WithheldCode,
-
+    /// A human-readable reason for why the key was not sent.
     pub reason: JsOption<String>,
     /// The other data of the unknown room key.
     #[serde(flatten)]