Make custom enum variants doc hidden

ruma-events/src/key/verification/cancel.rs

@@ -31,6 +31,10 @@ pub struct CancelEventContent {
 /// An error code for why the process/request was cancelled by the user.
 ///
 /// Custom error codes should use the Java package naming convention.
+///
+/// This type can hold an arbitrary string. To check for events that are not
+/// available as a documented variant here, use its string representation,
+/// obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 #[serde(from = "String", into = "String")]
@@ -70,13 +74,14 @@ pub enum CancelCode {
     /// The device receiving this error can ignore the verification request.
     Accepted,
 
-    /// Any code that is not part of the specification.
-    Custom(String),
+    #[doc(hidden)]
+    _Custom(String),
 }
 
-impl Display for CancelCode {
-    fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult {
-        let cancel_code_str = match *self {
+impl CancelCode {
+    /// Creates a string slice from this `CancelCode`.
+    pub fn as_str(&self) -> &str {
+        match *self {
             CancelCode::User => "m.user",
             CancelCode::Timeout => "m.timeout",
             CancelCode::UnknownTransaction => "m.unknown_transaction",
@@ -86,10 +91,14 @@ impl Display for CancelCode {
             CancelCode::UserMismatch => "m.user_mismatch",
             CancelCode::InvalidMessage => "m.invalid_message",
             CancelCode::Accepted => "m.accepted",
-            CancelCode::Custom(ref cancel_code) => cancel_code,
-        };
+            CancelCode::_Custom(ref cancel_code) => cancel_code,
+        }
+    }
+}
 
-        write!(f, "{}", cancel_code_str)
+impl Display for CancelCode {
+    fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult {
+        f.write_str(self.as_str())
     }
 }
 
@@ -108,7 +117,7 @@ where
             "m.user_mismatch" => CancelCode::UserMismatch,
             "m.invalid_message" => CancelCode::InvalidMessage,
             "m.accepted" => CancelCode::Accepted,
-            _ => CancelCode::Custom(s.into()),
+            _ => CancelCode::_Custom(s.into()),
         }
     }
 }
@@ -133,7 +142,7 @@ mod tests {
     #[test]
     fn custom_cancel_codes_serialize_to_display_form() {
         assert_eq!(
-            to_json_value(&CancelCode::Custom("io.ruma.test".into())).unwrap(),
+            to_json_value(&CancelCode::_Custom("io.ruma.test".into())).unwrap(),
             json!("io.ruma.test")
         );
     }
@@ -147,7 +156,7 @@ mod tests {
     fn custom_cancel_codes_deserialize_from_display_form() {
         assert_eq!(
             from_json_value::<CancelCode>(json!("io.ruma.test")).unwrap(),
-            CancelCode::Custom("io.ruma.test".into())
+            CancelCode::_Custom("io.ruma.test".into())
         )
     }
 }

ruma-events/src/room/message.rs

@@ -309,6 +309,10 @@ pub enum LimitType {
 }
 
 /// The format for the formatted representation of a message body.
+///
+/// This type can hold an arbitrary string. To check for events that are not
+/// available as a documented variant here, use its string representation,
+/// obtained through `.as_str()`.
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 pub enum MessageFormat {
@@ -316,16 +320,23 @@ pub enum MessageFormat {
     #[serde(rename = "org.matrix.custom.html")]
     Html,
 
-    /// A custom message format.
-    Custom(String),
+    #[doc(hidden)]
+    _Custom(String),
+}
+
+impl MessageFormat {
+    /// Creates a string slice from this `MessageFormat`.
+    pub fn as_str(&self) -> &str {
+        match self {
+            Self::Html => "org.matrix.custom.html",
+            Self::_Custom(ref message_format) => message_format,
+        }
+    }
 }
 
 impl fmt::Display for MessageFormat {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        match self {
-            Self::Html => f.write_str("org.matrix.custom.html"),
-            Self::Custom(fmt) => f.write_str(fmt),
-        }
+        f.write_str(self.as_str())
     }
 }
 

ruma-identifiers-validation/src/crypto_algorithms.rs

@@ -69,6 +69,10 @@ impl TryFrom<String> for ServerKeyAlgorithm {
 }
 
 /// An encryption algorithm to be used to encrypt messages sent to a room.
+///
+/// This type can hold an arbitrary string. To check for events that are not
+/// available as a documented variant here, use its string representation,
+/// obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq)]
 #[cfg_attr(
     feature = "serde",
@@ -83,19 +87,24 @@ pub enum EventEncryptionAlgorithm {
     /// Megolm version 1 using AES-256 and SHA-256.
     MegolmV1AesSha2,
 
-    /// Any algorithm that is not part of the specification.
-    Custom(String),
+    #[doc(hidden)]
+    _Custom(String),
+}
+
+impl EventEncryptionAlgorithm {
+    /// Creates a string slice from this `EventEncryptionAlgorithm`.
+    pub fn as_str(&self) -> &str {
+        match *self {
+            EventEncryptionAlgorithm::OlmV1Curve25519AesSha2 => "m.olm.v1.curve25519-aes-sha2",
+            EventEncryptionAlgorithm::MegolmV1AesSha2 => "m.megolm.v1.aes-sha2",
+            EventEncryptionAlgorithm::_Custom(ref algorithm) => algorithm,
+        }
+    }
 }
 
 impl Display for EventEncryptionAlgorithm {
     fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult {
-        let algorithm_str = match *self {
-            EventEncryptionAlgorithm::OlmV1Curve25519AesSha2 => "m.olm.v1.curve25519-aes-sha2",
-            EventEncryptionAlgorithm::MegolmV1AesSha2 => "m.megolm.v1.aes-sha2",
-            EventEncryptionAlgorithm::Custom(ref algorithm) => algorithm,
-        };
-
-        write!(f, "{}", algorithm_str)
+        f.write_str(self.as_str())
     }
 }
 
@@ -107,7 +116,7 @@ where
         match s.as_ref() {
             "m.olm.v1.curve25519-aes-sha2" => EventEncryptionAlgorithm::OlmV1Curve25519AesSha2,
             "m.megolm.v1.aes-sha2" => EventEncryptionAlgorithm::MegolmV1AesSha2,
-            _ => EventEncryptionAlgorithm::Custom(s.into()),
+            _ => EventEncryptionAlgorithm::_Custom(s.into()),
         }
     }
 }
@@ -145,7 +154,7 @@ mod tests {
             json!("m.olm.v1.curve25519-aes-sha2"),
         );
         serde_json_eq(
-            EventEncryptionAlgorithm::Custom("io.ruma.test".into()),
+            EventEncryptionAlgorithm::_Custom("io.ruma.test".into()),
             json!("io.ruma.test"),
         );
     }