From e8211daf3bbd7d2af69d994c11403c854cd1ea10 Mon Sep 17 00:00:00 2001
From: Sujay Jayakar <sujayakar@convex.dev>
Date: Wed, 13 Mar 2024 14:54:02 -0600
Subject: [PATCH] Add docstrings to model structs (#23418)

These aren't quite finished yet, but I left something for now.

GitOrigin-RevId: eeaaae14de3f47bda4f64eba90ab83efa6e740ec
---
 .../database/src/bootstrap_model/import_facing.rs   | 13 +++++++------
 .../database/src/bootstrap_model/system_metadata.rs |  7 +++++++
 2 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/crates/database/src/bootstrap_model/import_facing.rs b/crates/database/src/bootstrap_model/import_facing.rs
index 4c22b06e..8375fb34 100644
--- a/crates/database/src/bootstrap_model/import_facing.rs
+++ b/crates/database/src/bootstrap_model/import_facing.rs
@@ -29,6 +29,13 @@ use crate::{
     Transaction,
 };
 
+/// `ImportFacingModel` is similar to `UserFacingModel` but with a few
+/// differences for insertions:
+/// - the table for insertion is chosen by table id, not table name or number.
+/// - we allow the insertion to choose its document ID.
+/// - nonexistent tables won't be created implicitly.
+/// - the _creationTime may be user-specified.
+/// - only admin/system auth is allowed.
 pub struct ImportFacingModel<'a, RT: Runtime> {
     tx: &'a mut Transaction<RT>,
 }
@@ -39,12 +46,6 @@ impl<'a, RT: Runtime> ImportFacingModel<'a, RT> {
     }
 
     /// Inserts a new document as part of a snapshot import.
-    /// This is like `UserFacingModel::insert` with a few differences:
-    /// - the table for insertion is chosen by table id, not table name or
-    ///   number.
-    /// - nonexistent tables won't be created implicitly.
-    /// - the _creationTime may be user-specified.
-    /// - only admin/system auth is allowed.
     #[convex_macro::instrument_future]
     pub async fn insert(
         &mut self,
diff --git a/crates/database/src/bootstrap_model/system_metadata.rs b/crates/database/src/bootstrap_model/system_metadata.rs
index 413e1e88..65dcb31e 100644
--- a/crates/database/src/bootstrap_model/system_metadata.rs
+++ b/crates/database/src/bootstrap_model/system_metadata.rs
@@ -16,6 +16,13 @@ use crate::{
     Transaction,
 };
 
+/// We generally don't let `UserFacingModel` read or write system metadata,
+/// so this model is an alternative path for internal use for manipulating
+/// these tables.
+///
+/// Eventually, the goal is to entirely ban system metadata from
+/// `UserFacingModel` and strictly require that `SystemMetadataModel` only looks
+/// at system metadata.
 pub struct SystemMetadataModel<'a, RT: Runtime> {
     tx: &'a mut Transaction<RT>,
 }