Add documentation for Short*Id types

src/service/rooms/short.rs

@@ -9,27 +9,56 @@ use crate::{
 };
 
 macro_rules! short_id_type {
-    ($name:ident) => {
-        #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
-        #[repr(transparent)]
-        pub(crate) struct $name(u64);
+    ($($(#[$doc:meta])* struct $name:ident(u64);)*) => {
+        $(
+            #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+            #[repr(transparent)]
+            $(#[$doc])*
+            pub(crate) struct $name(u64);
 
-        impl $name {
-            pub(crate) fn new(id: u64) -> Self {
-                Self(id)
-            }
+            impl $name {
+                pub(crate) fn new(id: u64) -> Self {
+                    Self(id)
+                }
 
-            pub(crate) fn get(&self) -> u64 {
-                self.0
+                pub(crate) fn get(&self) -> u64 {
+                    self.0
+                }
             }
-        }
+        )*
     };
 }
 
-short_id_type!(ShortRoomId);
-short_id_type!(ShortEventId);
-short_id_type!(ShortStateHash);
-short_id_type!(ShortStateKey);
+short_id_type!(
+    /// Interned [RoomId].
+    ///
+    /// Created using [`get_shortroomid()`](Service::get_shortroomid) or
+    /// [`get_or_create_shortroomid()`](Service::get_or_create_shortroomid).
+    struct ShortRoomId(u64);
+    /// Interned [EventId].
+    ///
+    /// Created using
+    /// [`get_or_create_shorteventid()`](Service::get_or_create_shorteventid),
+    /// resolved using
+    /// [`get_eventid_from_short()`](Service::get_eventid_from_short).
+    struct ShortEventId(u64);
+    /// Interned hash of concatenated state events.
+    ///
+    /// Equal state sets do not necessarily correspond to equal short state
+    /// hashes, because the calculated hash is dependent on `HashSet`
+    /// iteration order.
+    ///
+    /// Created using
+    /// [`get_or_create_shortstatehash()`](Service::get_or_create_shortstatehash).
+    struct ShortStateHash(u64);
+    /// Interned `(event type, state key)` tuple.
+    ///
+    /// Created using [`get_shortstatekey()`](Service::get_shortstatekey) or
+    /// [`get_or_create_shortstatekey()`](Service::get_or_create_shortstatekey),
+    /// resolved using
+    /// [`get_statekey_from_short()`](Service::get_statekey_from_short).
+    struct ShortStateKey(u64);
+);
 
 mod data;