identifiers: Document how to create a DeviceId

crates/ruma-identifiers/src/device_id.rs

@@ -6,6 +6,24 @@ opaque_identifier! {
     ///
     /// Device identifiers in Matrix are completely opaque character sequences. This type is
     /// provided simply for its semantic value.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use ruma_identifiers::{DeviceId, device_id};
+    ///
+    /// let random_id = DeviceId::new();
+    /// assert_eq!(random_id.as_str().len(), 8);
+    ///
+    /// let static_id = device_id!("01234567");
+    /// assert_eq!(static_id.as_str(), "01234567");
+    ///
+    /// let ref_id: &DeviceId = "abcdefghi".into();
+    /// assert_eq!(ref_id.as_str(), "abcdefghi");
+    ///
+    /// let owned_id: Box<DeviceId> = "ijklmnop".into();
+    /// assert_eq!(owned_id.as_str(), "ijklmnop");
+    /// ```
     pub type DeviceId;
 }
 
@@ -25,4 +43,23 @@ mod tests {
     fn generate_device_id() {
         assert_eq!(DeviceId::new().as_str().len(), 8);
     }
+
+    #[test]
+    fn create_device_id_from_str() {
+        let ref_id: &DeviceId = "abcdefgh".into();
+        assert_eq!(ref_id.as_str(), "abcdefgh");
+    }
+
+    #[test]
+    fn create_boxed_device_id_from_str() {
+        let box_id: Box<DeviceId> = "12345678".into();
+        assert_eq!(box_id.as_str(), "12345678");
+    }
+
+    #[test]
+    fn create_device_id_from_box() {
+        let box_str: Box<str> = "ijklmnop".into();
+        let device_id: Box<DeviceId> = DeviceId::from_owned(box_str);
+        assert_eq!(device_id.as_str(), "ijklmnop");
+    }
 }