Add notification doc comments

Max Brunsfeld created 2 years ago

Change summary

crates/collab/src/db/queries/notifications.rs |  6 +++---
crates/rpc/src/notification.rs                | 20 ++++++++++++++++++--
2 files changed, 21 insertions(+), 5 deletions(-)

Detailed changes

crates/collab/src/db/queries/notifications.rs

@@ -42,7 +42,7 @@ impl Database {
                 let Some(kind) = NotificationKind::from_i32(row.kind) else {
                     continue;
                 };
-                let Some(notification) = Notification::from_fields(
+                let Some(notification) = Notification::from_parts(
                     kind,
                     [
                         row.entity_id_1.map(|id| id as u64),
@@ -54,7 +54,7 @@ impl Database {
                 };
 
                 // Gather the ids of all associated entities.
-                let (_, associated_entities) = notification.to_fields();
+                let (_, associated_entities) = notification.to_parts();
                 for entity in associated_entities {
                     let Some((id, kind)) = entity else {
                         break;
@@ -124,7 +124,7 @@ impl Database {
         notification: Notification,
         tx: &DatabaseTransaction,
     ) -> Result<()> {
-        let (kind, associated_entities) = notification.to_fields();
+        let (kind, associated_entities) = notification.to_parts();
         notification::ActiveModel {
             recipient_id: ActiveValue::Set(recipient_id),
             kind: ActiveValue::Set(kind as i32),

crates/rpc/src/notification.rs

@@ -34,7 +34,13 @@ pub enum NotificationEntityKind {
 }
 
 impl Notification {
-    pub fn from_fields(kind: NotificationKind, entity_ids: [Option<u64>; 3]) -> Option<Self> {
+    /// Load this notification from its generic representation, which is
+    /// used to represent it in the database, and in the wire protocol.
+    ///
+    /// The order in which a given notification type's fields are listed must
+    /// match the order they're listed in the `to_parts` method, and it must
+    /// not change, because they're stored in that order in the database.
+    pub fn from_parts(kind: NotificationKind, entity_ids: [Option<u64>; 3]) -> Option<Self> {
         use NotificationKind::*;
 
         Some(match kind {
@@ -53,7 +59,17 @@ impl Notification {
         })
     }
 
-    pub fn to_fields(&self) -> (NotificationKind, [Option<(u64, NotificationEntityKind)>; 3]) {
+    /// Convert this notification into its generic representation, which is
+    /// used to represent it in the database, and in the wire protocol.
+    ///
+    /// The order in which a given notification type's fields are listed must
+    /// match the order they're listed in the `from_parts` method, and it must
+    /// not change, because they're stored in that order in the database.
+    ///
+    /// Along with each field, provide the kind of entity that the field refers
+    /// to. This is used to load the associated entities for a batch of
+    /// notifications from the database.
+    pub fn to_parts(&self) -> (NotificationKind, [Option<(u64, NotificationEntityKind)>; 3]) {
         use NotificationKind::*;
 
         match self {