Add more documentation to collab (#4095)

This PR adds more documentation to the `collab` crate.

Release Notes:

- N/A

---------

Co-authored-by: Conrad <conrad@zed.dev>

crates/collab/src/auth.rs

@@ -27,6 +27,8 @@ lazy_static! {
     .unwrap();
 }
 
+/// Validates the authorization header. This has two mechanisms, one for the ADMIN_TOKEN
+/// and one for the access tokens that we issue.
 pub async fn validate_header<B>(mut req: Request<B>, next: Next<B>) -> impl IntoResponse {
     let mut auth_header = req
         .headers()
@@ -88,6 +90,8 @@ struct AccessTokenJson {
     token: String,
 }
 
+/// Creates a new access token to identify the given user. before returning it, you should
+/// encrypt it with the user's public key.
 pub async fn create_access_token(db: &db::Database, user_id: UserId) -> Result<String> {
     const VERSION: usize = 1;
     let access_token = rpc::auth::random_token();
@@ -122,6 +126,8 @@ fn hash_access_token(token: &str) -> Result<String> {
         .to_string())
 }
 
+/// Encrypts the given access token with the given public key to avoid leaking it on the way
+/// to the client.
 pub fn encrypt_access_token(access_token: &str, public_key: String) -> Result<String> {
     let native_app_public_key =
         rpc::auth::PublicKey::try_from(public_key).context("failed to parse app public key")?;
@@ -131,6 +137,7 @@ pub fn encrypt_access_token(access_token: &str, public_key: String) -> Result<St
     Ok(encrypted_access_token)
 }
 
+/// verify access token returns true if the given token is valid for the given user.
 pub async fn verify_access_token(token: &str, user_id: UserId, db: &Arc<Database>) -> Result<bool> {
     let token: AccessTokenJson = serde_json::from_str(&token)?;
 

crates/collab/src/db.rs

@@ -47,6 +47,8 @@ pub use ids::*;
 pub use sea_orm::ConnectOptions;
 pub use tables::user::Model as User;
 
+/// Database gives you a handle that lets you access the database.
+/// It handles pooling internally.
 pub struct Database {
     options: ConnectOptions,
     pool: DatabaseConnection,
@@ -62,6 +64,7 @@ pub struct Database {
 // The `Database` type has so many methods that its impl blocks are split into
 // separate files in the `queries` folder.
 impl Database {
+    /// Connects to the database with the given options
     pub async fn new(options: ConnectOptions, executor: Executor) -> Result<Self> {
         sqlx::any::install_default_drivers();
         Ok(Self {
@@ -82,6 +85,7 @@ impl Database {
         self.rooms.clear();
     }
 
+    /// Runs the database migrations.
     pub async fn migrate(
         &self,
         migrations_path: &Path,
@@ -123,11 +127,15 @@ impl Database {
         Ok(new_migrations)
     }
 
+    /// Initializes static data that resides in the database by upserting it.
     pub async fn initialize_static_data(&mut self) -> Result<()> {
         self.initialize_notification_kinds().await?;
         Ok(())
     }
 
+    /// Transaction runs things in a transaction. If you want to call other methods
+    /// and pass the transaction around you need to reborrow the transaction at each
+    /// call site with: `&*tx`.
     pub async fn transaction<F, Fut, T>(&self, f: F) -> Result<T>
     where
         F: Send + Fn(TransactionHandle) -> Fut,
@@ -160,6 +168,7 @@ impl Database {
         self.run(body).await
     }
 
+    /// The same as room_transaction, but if you need to only optionally return a Room.
     async fn optional_room_transaction<F, Fut, T>(&self, f: F) -> Result<Option<RoomGuard<T>>>
     where
         F: Send + Fn(TransactionHandle) -> Fut,
@@ -210,6 +219,9 @@ impl Database {
         self.run(body).await
     }
 
+    /// room_transaction runs the block in a transaction. It returns a RoomGuard, that keeps
+    /// the database locked until it is dropped. This ensures that updates sent to clients are
+    /// properly serialized with respect to database changes.
     async fn room_transaction<F, Fut, T>(&self, room_id: RoomId, f: F) -> Result<RoomGuard<T>>
     where
         F: Send + Fn(TransactionHandle) -> Fut,
@@ -330,6 +342,7 @@ fn is_serialization_error(error: &Error) -> bool {
     }
 }
 
+/// A handle to a [`DatabaseTransaction`].
 pub struct TransactionHandle(Arc<Option<DatabaseTransaction>>);
 
 impl Deref for TransactionHandle {
@@ -340,6 +353,8 @@ impl Deref for TransactionHandle {
     }
 }
 
+/// [`RoomGuard`] keeps a database transaction alive until it is dropped.
+/// so that updates to rooms are serialized.
 pub struct RoomGuard<T> {
     data: T,
     _guard: OwnedMutexGuard<()>,
@@ -361,6 +376,7 @@ impl<T> DerefMut for RoomGuard<T> {
 }
 
 impl<T> RoomGuard<T> {
+    /// Returns the inner value of the guard.
     pub fn into_inner(self) -> T {
         self.data
     }
@@ -420,12 +436,14 @@ pub struct WaitlistSummary {
     pub unknown_count: i64,
 }
 
+/// The parameters to create a new user.
 #[derive(Debug, Serialize, Deserialize)]
 pub struct NewUserParams {
     pub github_login: String,
     pub github_user_id: i32,
 }
 
+/// The result of creating a new user.
 #[derive(Debug)]
 pub struct NewUserResult {
     pub user_id: UserId,
@@ -434,6 +452,7 @@ pub struct NewUserResult {
     pub signup_device_id: Option<String>,
 }
 
+/// The result of moving a channel.
 #[derive(Debug)]
 pub struct MoveChannelResult {
     pub participants_to_update: HashMap<UserId, ChannelsForUser>,
@@ -441,18 +460,21 @@ pub struct MoveChannelResult {
     pub moved_channels: HashSet<ChannelId>,
 }
 
+/// The result of renaming a channel.
 #[derive(Debug)]
 pub struct RenameChannelResult {
     pub channel: Channel,
     pub participants_to_update: HashMap<UserId, Channel>,
 }
 
+/// The result of creating a channel.
 #[derive(Debug)]
 pub struct CreateChannelResult {
     pub channel: Channel,
     pub participants_to_update: Vec<(UserId, ChannelsForUser)>,
 }
 
+/// The result of setting a channel's visibility.
 #[derive(Debug)]
 pub struct SetChannelVisibilityResult {
     pub participants_to_update: HashMap<UserId, ChannelsForUser>,
@@ -460,6 +482,7 @@ pub struct SetChannelVisibilityResult {
     pub channels_to_remove: Vec<ChannelId>,
 }
 
+/// The result of updating a channel membership.
 #[derive(Debug)]
 pub struct MembershipUpdated {
     pub channel_id: ChannelId,
@@ -467,12 +490,14 @@ pub struct MembershipUpdated {
     pub removed_channels: Vec<ChannelId>,
 }
 
+/// The result of setting a member's role.
 #[derive(Debug)]
 pub enum SetMemberRoleResult {
     InviteUpdated(Channel),
     MembershipUpdated(MembershipUpdated),
 }
 
+/// The result of inviting a member to a channel.
 #[derive(Debug)]
 pub struct InviteMemberResult {
     pub channel: Channel,
@@ -497,6 +522,7 @@ pub struct Channel {
     pub name: String,
     pub visibility: ChannelVisibility,
     pub role: ChannelRole,
+    /// parent_path is the channel ids from the root to this one (not including this one)
     pub parent_path: Vec<ChannelId>,
 }
 

crates/collab/src/db/ids.rs

@@ -19,19 +19,23 @@ macro_rules! id_type {
             Deserialize,
             DeriveValueType,
         )]
+        #[allow(missing_docs)]
         #[serde(transparent)]
         pub struct $name(pub i32);
 
         impl $name {
             #[allow(unused)]
+            #[allow(missing_docs)]
             pub const MAX: Self = Self(i32::MAX);
 
             #[allow(unused)]
+            #[allow(missing_docs)]
             pub fn from_proto(value: u64) -> Self {
                 Self(value as i32)
             }
 
             #[allow(unused)]
+            #[allow(missing_docs)]
             pub fn to_proto(self) -> u64 {
                 self.0 as u64
             }
@@ -84,21 +88,28 @@ id_type!(FlagId);
 id_type!(NotificationId);
 id_type!(NotificationKindId);
 
+/// ChannelRole gives you permissions for both channels and calls.
 #[derive(Eq, PartialEq, Copy, Clone, Debug, EnumIter, DeriveActiveEnum, Default, Hash)]
 #[sea_orm(rs_type = "String", db_type = "String(None)")]
 pub enum ChannelRole {
+    /// Admin can read/write and change permissions.
     #[sea_orm(string_value = "admin")]
     Admin,
+    /// Member can read/write, but not change pemissions.
     #[sea_orm(string_value = "member")]
     #[default]
     Member,
+    /// Guest can read, but not write.
+    /// (thought they can use the channel chat)
     #[sea_orm(string_value = "guest")]
     Guest,
+    /// Banned may not read.
     #[sea_orm(string_value = "banned")]
     Banned,
 }
 
 impl ChannelRole {
+    /// Returns true if this role is more powerful than the other role.
     pub fn should_override(&self, other: Self) -> bool {
         use ChannelRole::*;
         match self {
@@ -109,6 +120,7 @@ impl ChannelRole {
         }
     }
 
+    /// Returns the maximal role between the two
     pub fn max(&self, other: Self) -> Self {
         if self.should_override(other) {
             *self
@@ -117,6 +129,7 @@ impl ChannelRole {
         }
     }
 
+    /// True if the role allows access to all descendant channels
     pub fn can_see_all_descendants(&self) -> bool {
         use ChannelRole::*;
         match self {
@@ -125,6 +138,7 @@ impl ChannelRole {
         }
     }
 
+    /// True if the role only allows access to public descendant channels
     pub fn can_only_see_public_descendants(&self) -> bool {
         use ChannelRole::*;
         match self {
@@ -133,6 +147,7 @@ impl ChannelRole {
         }
     }
 
+    /// True if the role can share screen/microphone/projects into rooms.
     pub fn can_publish_to_rooms(&self) -> bool {
         use ChannelRole::*;
         match self {
@@ -141,6 +156,7 @@ impl ChannelRole {
         }
     }
 
+    /// True if the role can edit shared projects.
     pub fn can_edit_projects(&self) -> bool {
         use ChannelRole::*;
         match self {
@@ -149,6 +165,7 @@ impl ChannelRole {
         }
     }
 
+    /// True if the role can read shared projects.
     pub fn can_read_projects(&self) -> bool {
         use ChannelRole::*;
         match self {
@@ -187,11 +204,14 @@ impl Into<i32> for ChannelRole {
     }
 }
 
+/// ChannelVisibility controls whether channels are public or private.
 #[derive(Eq, PartialEq, Copy, Clone, Debug, EnumIter, DeriveActiveEnum, Default, Hash)]
 #[sea_orm(rs_type = "String", db_type = "String(None)")]
 pub enum ChannelVisibility {
+    /// Public channels are visible to anyone with the link. People join with the Guest role by default.
     #[sea_orm(string_value = "public")]
     Public,
+    /// Members channels are only visible to members of this channel or its parents.
     #[sea_orm(string_value = "members")]
     #[default]
     Members,

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

@@ -2,6 +2,7 @@ use super::*;
 use sea_orm::sea_query::Query;
 
 impl Database {
+    /// Creates a new access token for the given user.
     pub async fn create_access_token(
         &self,
         user_id: UserId,
@@ -39,6 +40,7 @@ impl Database {
         .await
     }
 
+    /// Retrieves the access token with the given ID.
     pub async fn get_access_token(
         &self,
         access_token_id: AccessTokenId,

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

@@ -9,6 +9,8 @@ pub struct LeftChannelBuffer {
 }
 
 impl Database {
+    /// Open a channel buffer. Returns the current contents, and adds you to the list of people
+    /// to notify on changes.
     pub async fn join_channel_buffer(
         &self,
         channel_id: ChannelId,
@@ -121,6 +123,7 @@ impl Database {
         .await
     }
 
+    /// Rejoin a channel buffer (after a connection interruption)
     pub async fn rejoin_channel_buffers(
         &self,
         buffers: &[proto::ChannelBufferVersion],
@@ -232,6 +235,7 @@ impl Database {
         .await
     }
 
+    /// Clear out any buffer collaborators who are no longer collaborating.
     pub async fn clear_stale_channel_buffer_collaborators(
         &self,
         channel_id: ChannelId,
@@ -274,6 +278,7 @@ impl Database {
         .await
     }
 
+    /// Close the channel buffer, and stop receiving updates for it.
     pub async fn leave_channel_buffer(
         &self,
         channel_id: ChannelId,
@@ -286,6 +291,7 @@ impl Database {
         .await
     }
 
+    /// Close the channel buffer, and stop receiving updates for it.
     pub async fn channel_buffer_connection_lost(
         &self,
         connection: ConnectionId,
@@ -309,6 +315,7 @@ impl Database {
         Ok(())
     }
 
+    /// Close all open channel buffers
     pub async fn leave_channel_buffers(
         &self,
         connection: ConnectionId,
@@ -342,7 +349,7 @@ impl Database {
         .await
     }
 
-    pub async fn leave_channel_buffer_internal(
+    async fn leave_channel_buffer_internal(
         &self,
         channel_id: ChannelId,
         connection: ConnectionId,
@@ -798,6 +805,7 @@ impl Database {
         Ok(changes)
     }
 
+    /// Returns the latest operations for the buffers with the specified IDs.
     pub async fn get_latest_operations_for_buffers(
         &self,
         buffer_ids: impl IntoIterator<Item = BufferId>,

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

@@ -40,6 +40,7 @@ impl Database {
             .id)
     }
 
+    /// Creates a new channel.
     pub async fn create_channel(
         &self,
         name: &str,
@@ -97,6 +98,7 @@ impl Database {
         .await
     }
 
+    /// Adds a user to the specified channel.
     pub async fn join_channel(
         &self,
         channel_id: ChannelId,
@@ -179,6 +181,7 @@ impl Database {
         .await
     }
 
+    /// Sets the visibiltity of the given channel.
     pub async fn set_channel_visibility(
         &self,
         channel_id: ChannelId,
@@ -258,6 +261,7 @@ impl Database {
         .await
     }
 
+    /// Deletes the channel with the specified ID.
     pub async fn delete_channel(
         &self,
         channel_id: ChannelId,
@@ -294,6 +298,7 @@ impl Database {
         .await
     }
 
+    /// Invites a user to a channel as a member.
     pub async fn invite_channel_member(
         &self,
         channel_id: ChannelId,
@@ -349,6 +354,7 @@ impl Database {
         Ok(new_name)
     }
 
+    /// Renames the specified channel.
     pub async fn rename_channel(
         &self,
         channel_id: ChannelId,
@@ -387,6 +393,7 @@ impl Database {
         .await
     }
 
+    /// accept or decline an invite to join a channel
     pub async fn respond_to_channel_invite(
         &self,
         channel_id: ChannelId,
@@ -486,6 +493,7 @@ impl Database {
         })
     }
 
+    /// Removes a channel member.
     pub async fn remove_channel_member(
         &self,
         channel_id: ChannelId,
@@ -530,6 +538,7 @@ impl Database {
         .await
     }
 
+    /// Returns all channel invites for the user with the given ID.
     pub async fn get_channel_invites_for_user(&self, user_id: UserId) -> Result<Vec<Channel>> {
         self.transaction(|tx| async move {
             let mut role_for_channel: HashMap<ChannelId, ChannelRole> = HashMap::default();
@@ -565,6 +574,7 @@ impl Database {
         .await
     }
 
+    /// Returns all channels for the user with the given ID.
     pub async fn get_channels_for_user(&self, user_id: UserId) -> Result<ChannelsForUser> {
         self.transaction(|tx| async move {
             let tx = tx;
@@ -574,6 +584,8 @@ impl Database {
         .await
     }
 
+    /// Returns all channels for the user with the given ID that are descendants
+    /// of the specified ancestor channel.
     pub async fn get_user_channels(
         &self,
         user_id: UserId,
@@ -743,6 +755,7 @@ impl Database {
         Ok(results)
     }
 
+    /// Sets the role for the specified channel member.
     pub async fn set_channel_member_role(
         &self,
         channel_id: ChannelId,
@@ -786,6 +799,7 @@ impl Database {
         .await
     }
 
+    /// Returns the details for the specified channel member.
     pub async fn get_channel_participant_details(
         &self,
         channel_id: ChannelId,
@@ -911,6 +925,7 @@ impl Database {
             .collect())
     }
 
+    /// Returns the participants in the given channel.
     pub async fn get_channel_participants(
         &self,
         channel: &channel::Model,
@@ -925,6 +940,7 @@ impl Database {
             .collect())
     }
 
+    /// Returns whether the given user is an admin in the specified channel.
     pub async fn check_user_is_channel_admin(
         &self,
         channel: &channel::Model,
@@ -943,6 +959,7 @@ impl Database {
         }
     }
 
+    /// Returns whether the given user is a member of the specified channel.
     pub async fn check_user_is_channel_member(
         &self,
         channel: &channel::Model,
@@ -958,6 +975,7 @@ impl Database {
         }
     }
 
+    /// Returns whether the given user is a participant in the specified channel.
     pub async fn check_user_is_channel_participant(
         &self,
         channel: &channel::Model,
@@ -975,6 +993,7 @@ impl Database {
         }
     }
 
+    /// Returns a user's pending invite for the given channel, if one exists.
     pub async fn pending_invite_for_channel(
         &self,
         channel: &channel::Model,
@@ -991,7 +1010,7 @@ impl Database {
         Ok(row)
     }
 
-    pub async fn public_parent_channel(
+    async fn public_parent_channel(
         &self,
         channel: &channel::Model,
         tx: &DatabaseTransaction,
@@ -1003,7 +1022,7 @@ impl Database {
         Ok(path.pop())
     }
 
-    pub async fn public_ancestors_including_self(
+    pub(crate) async fn public_ancestors_including_self(
         &self,
         channel: &channel::Model,
         tx: &DatabaseTransaction,
@@ -1018,6 +1037,7 @@ impl Database {
         Ok(visible_channels)
     }
 
+    /// Returns the role for a user in the given channel.
     pub async fn channel_role_for_user(
         &self,
         channel: &channel::Model,
@@ -1143,7 +1163,7 @@ impl Database {
             .await?)
     }
 
-    /// Returns the channel with the given ID
+    /// Returns the channel with the given ID.
     pub async fn get_channel(&self, channel_id: ChannelId, user_id: UserId) -> Result<Channel> {
         self.transaction(|tx| async move {
             let channel = self.get_channel_internal(channel_id, &*tx).await?;
@@ -1156,7 +1176,7 @@ impl Database {
         .await
     }
 
-    pub async fn get_channel_internal(
+    pub(crate) async fn get_channel_internal(
         &self,
         channel_id: ChannelId,
         tx: &DatabaseTransaction,

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

@@ -1,6 +1,7 @@
 use super::*;
 
 impl Database {
+    /// Retrieves the contacts for the user with the given ID.
     pub async fn get_contacts(&self, user_id: UserId) -> Result<Vec<Contact>> {
         #[derive(Debug, FromQueryResult)]
         struct ContactWithUserBusyStatuses {
@@ -86,6 +87,7 @@ impl Database {
         .await
     }
 
+    /// Returns whether the given user is a busy (on a call).
     pub async fn is_user_busy(&self, user_id: UserId) -> Result<bool> {
         self.transaction(|tx| async move {
             let participant = room_participant::Entity::find()
@@ -97,6 +99,9 @@ impl Database {
         .await
     }
 
+    /// Returns whether the user with `user_id_1` has the user with `user_id_2` as a contact.
+    ///
+    /// In order for this to return `true`, `user_id_2` must have an accepted invite from `user_id_1`.
     pub async fn has_contact(&self, user_id_1: UserId, user_id_2: UserId) -> Result<bool> {
         self.transaction(|tx| async move {
             let (id_a, id_b) = if user_id_1 < user_id_2 {
@@ -119,6 +124,7 @@ impl Database {
         .await
     }
 
+    /// Invite the user with `receiver_id` to be a contact of the user with `sender_id`.
     pub async fn send_contact_request(
         &self,
         sender_id: UserId,
@@ -231,6 +237,7 @@ impl Database {
         .await
     }
 
+    /// Dismisses a contact notification for the given user.
     pub async fn dismiss_contact_notification(
         &self,
         user_id: UserId,
@@ -272,6 +279,7 @@ impl Database {
         .await
     }
 
+    /// Accept or decline a contact request
     pub async fn respond_to_contact_request(
         &self,
         responder_id: UserId,

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

@@ -4,6 +4,7 @@ use sea_orm::TryInsertResult;
 use time::OffsetDateTime;
 
 impl Database {
+    /// Inserts a record representing a user joining the chat for a given channel.
     pub async fn join_channel_chat(
         &self,
         channel_id: ChannelId,
@@ -28,6 +29,7 @@ impl Database {
         .await
     }
 
+    /// Removes `channel_chat_participant` records associated with the given connection ID.
     pub async fn channel_chat_connection_lost(
         &self,
         connection_id: ConnectionId,
@@ -47,6 +49,8 @@ impl Database {
         Ok(())
     }
 
+    /// Removes `channel_chat_participant` records associated with the given user ID so they
+    /// will no longer get chat notifications.
     pub async fn leave_channel_chat(
         &self,
         channel_id: ChannelId,
@@ -72,6 +76,9 @@ impl Database {
         .await
     }
 
+    /// Retrieves the messages in the specified channel.
+    ///
+    /// Use `before_message_id` to paginate through the channel's messages.
     pub async fn get_channel_messages(
         &self,
         channel_id: ChannelId,
@@ -103,6 +110,7 @@ impl Database {
         .await
     }
 
+    /// Returns the channel messages with the given IDs.
     pub async fn get_channel_messages_by_id(
         &self,
         user_id: UserId,
@@ -190,6 +198,7 @@ impl Database {
         Ok(messages)
     }
 
+    /// Creates a new channel message.
     pub async fn create_channel_message(
         &self,
         channel_id: ChannelId,
@@ -376,6 +385,7 @@ impl Database {
         Ok(())
     }
 
+    /// Returns the unseen messages for the given user in the specified channels.
     pub async fn unseen_channel_messages(
         &self,
         user_id: UserId,
@@ -449,6 +459,7 @@ impl Database {
         Ok(changes)
     }
 
+    /// Removes the channel message with the given ID.
     pub async fn remove_channel_message(
         &self,
         channel_id: ChannelId,

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

@@ -2,6 +2,7 @@ use super::*;
 use rpc::Notification;
 
 impl Database {
+    /// Initializes the different kinds of notifications by upserting records for them.
     pub async fn initialize_notification_kinds(&mut self) -> Result<()> {
         notification_kind::Entity::insert_many(Notification::all_variant_names().iter().map(
             |kind| notification_kind::ActiveModel {
@@ -28,6 +29,7 @@ impl Database {
         Ok(())
     }
 
+    /// Returns the notifications for the given recipient.
     pub async fn get_notifications(
         &self,
         recipient_id: UserId,
@@ -140,6 +142,7 @@ impl Database {
             .await
     }
 
+    /// Marks the given notification as read.
     pub async fn mark_notification_as_read(
         &self,
         recipient_id: UserId,
@@ -150,6 +153,7 @@ impl Database {
             .await
     }
 
+    /// Marks the notification with the given ID as read.
     pub async fn mark_notification_as_read_by_id(
         &self,
         recipient_id: UserId,

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

@@ -1,6 +1,7 @@
 use super::*;
 
 impl Database {
+    /// Returns the count of all projects, excluding ones marked as admin.
     pub async fn project_count_excluding_admins(&self) -> Result<usize> {
         #[derive(Copy, Clone, Debug, EnumIter, DeriveColumn)]
         enum QueryAs {
@@ -21,6 +22,7 @@ impl Database {
         .await
     }
 
+    /// Shares a project with the given room.
     pub async fn share_project(
         &self,
         room_id: RoomId,
@@ -100,6 +102,7 @@ impl Database {
         .await
     }
 
+    /// Unshares the given project.
     pub async fn unshare_project(
         &self,
         project_id: ProjectId,
@@ -126,6 +129,7 @@ impl Database {
         .await
     }
 
+    /// Updates the worktrees associated with the given project.
     pub async fn update_project(
         &self,
         project_id: ProjectId,
@@ -346,6 +350,7 @@ impl Database {
         .await
     }
 
+    /// Updates the diagnostic summary for the given connection.
     pub async fn update_diagnostic_summary(
         &self,
         update: &proto::UpdateDiagnosticSummary,
@@ -401,6 +406,7 @@ impl Database {
         .await
     }
 
+    /// Starts the language server for the given connection.
     pub async fn start_language_server(
         &self,
         update: &proto::StartLanguageServer,
@@ -447,6 +453,7 @@ impl Database {
         .await
     }
 
+    /// Updates the worktree settings for the given connection.
     pub async fn update_worktree_settings(
         &self,
         update: &proto::UpdateWorktreeSettings,
@@ -499,6 +506,7 @@ impl Database {
         .await
     }
 
+    /// Adds the given connection to the specified project.
     pub async fn join_project(
         &self,
         project_id: ProjectId,
@@ -704,6 +712,7 @@ impl Database {
         .await
     }
 
+    /// Removes the given connection from the specified project.
     pub async fn leave_project(
         &self,
         project_id: ProjectId,
@@ -805,6 +814,7 @@ impl Database {
         .map(|guard| guard.into_inner())
     }
 
+    /// Returns the host connection for a read-only request to join a shared project.
     pub async fn host_for_read_only_project_request(
         &self,
         project_id: ProjectId,
@@ -842,6 +852,7 @@ impl Database {
         .map(|guard| guard.into_inner())
     }
 
+    /// Returns the host connection for a request to join a shared project.
     pub async fn host_for_mutating_project_request(
         &self,
         project_id: ProjectId,
@@ -927,6 +938,10 @@ impl Database {
         .await
     }
 
+    /// Returns the connection IDs in the given project.
+    ///
+    /// The provided `connection_id` must also be a collaborator in the project,
+    /// otherwise an error will be returned.
     pub async fn project_connection_ids(
         &self,
         project_id: ProjectId,
@@ -976,6 +991,7 @@ impl Database {
         Ok(guest_connection_ids)
     }
 
+    /// Returns the [`RoomId`] for the given project.
     pub async fn room_id_for_project(&self, project_id: ProjectId) -> Result<RoomId> {
         self.transaction(|tx| async move {
             let project = project::Entity::find_by_id(project_id)
@@ -1020,6 +1036,7 @@ impl Database {
         .await
     }
 
+    /// Adds the given follower connection as a follower of the given leader connection.
     pub async fn follow(
         &self,
         room_id: RoomId,
@@ -1050,6 +1067,7 @@ impl Database {
         .await
     }
 
+    /// Removes the given follower connection as a follower of the given leader connection.
     pub async fn unfollow(
         &self,
         room_id: RoomId,

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

@@ -1,6 +1,7 @@
 use super::*;
 
 impl Database {
+    /// Clears all room participants in rooms attached to a stale server.
     pub async fn clear_stale_room_participants(
         &self,
         room_id: RoomId,
@@ -78,6 +79,7 @@ impl Database {
         .await
     }
 
+    /// Returns the incoming calls for user with the given ID.
     pub async fn incoming_call_for_user(
         &self,
         user_id: UserId,
@@ -102,6 +104,7 @@ impl Database {
         .await
     }
 
+    /// Creates a new room.
     pub async fn create_room(
         &self,
         user_id: UserId,
@@ -394,6 +397,7 @@ impl Database {
         Ok(participant_index)
     }
 
+    /// Returns the channel ID for the given room, if it has one.
     pub async fn channel_id_for_room(&self, room_id: RoomId) -> Result<Option<ChannelId>> {
         self.transaction(|tx| async move {
             let room: Option<room::Model> = room::Entity::find()
@@ -944,6 +948,7 @@ impl Database {
         .await
     }
 
+    /// Updates the location of a participant in the given room.
     pub async fn update_room_participant_location(
         &self,
         room_id: RoomId,
@@ -1004,6 +1009,7 @@ impl Database {
         .await
     }
 
+    /// Sets the role of a participant in the given room.
     pub async fn set_room_participant_role(
         &self,
         admin_id: UserId,

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

@@ -1,6 +1,7 @@
 use super::*;
 
 impl Database {
+    /// Creates a new server in the given environment.
     pub async fn create_server(&self, environment: &str) -> Result<ServerId> {
         self.transaction(|tx| async move {
             let server = server::ActiveModel {
@@ -14,6 +15,10 @@ impl Database {
         .await
     }
 
+    /// Returns the IDs of resources associated with stale servers.
+    ///
+    /// A server is stale if it is in the specified `environment` and does not
+    /// match the provided `new_server_id`.
     pub async fn stale_server_resource_ids(
         &self,
         environment: &str,
@@ -61,6 +66,7 @@ impl Database {
         .await
     }
 
+    /// Deletes any stale servers in the environment that don't match the `new_server_id`.
     pub async fn delete_stale_servers(
         &self,
         environment: &str,

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

@@ -1,6 +1,7 @@
 use super::*;
 
 impl Database {
+    /// Creates a new user.
     pub async fn create_user(
         &self,
         email_address: &str,
@@ -35,11 +36,13 @@ impl Database {
         .await
     }
 
+    /// Returns a user by ID. There are no access checks here, so this should only be used internally.
     pub async fn get_user_by_id(&self, id: UserId) -> Result<Option<user::Model>> {
         self.transaction(|tx| async move { Ok(user::Entity::find_by_id(id).one(&*tx).await?) })
             .await
     }
 
+    /// Returns all users by ID. There are no access checks here, so this should only be used internally.
     pub async fn get_users_by_ids(&self, ids: Vec<UserId>) -> Result<Vec<user::Model>> {
         self.transaction(|tx| async {
             let tx = tx;
@@ -51,6 +54,7 @@ impl Database {
         .await
     }
 
+    /// Returns a user by GitHub login. There are no access checks here, so this should only be used internally.
     pub async fn get_user_by_github_login(&self, github_login: &str) -> Result<Option<User>> {
         self.transaction(|tx| async move {
             Ok(user::Entity::find()
@@ -111,6 +115,8 @@ impl Database {
         .await
     }
 
+    /// get_all_users returns the next page of users. To get more call again with
+    /// the same limit and the page incremented by 1.
     pub async fn get_all_users(&self, page: u32, limit: u32) -> Result<Vec<User>> {
         self.transaction(|tx| async move {
             Ok(user::Entity::find()
@@ -123,6 +129,7 @@ impl Database {
         .await
     }
 
+    /// Returns the metrics id for the user.
     pub async fn get_user_metrics_id(&self, id: UserId) -> Result<String> {
         #[derive(Copy, Clone, Debug, EnumIter, DeriveColumn)]
         enum QueryAs {
@@ -142,6 +149,7 @@ impl Database {
         .await
     }
 
+    /// Set "connected_once" on the user for analytics.
     pub async fn set_user_connected_once(&self, id: UserId, connected_once: bool) -> Result<()> {
         self.transaction(|tx| async move {
             user::Entity::update_many()
@@ -157,6 +165,7 @@ impl Database {
         .await
     }
 
+    /// hard delete the user.
     pub async fn destroy_user(&self, id: UserId) -> Result<()> {
         self.transaction(|tx| async move {
             access_token::Entity::delete_many()
@@ -169,6 +178,7 @@ impl Database {
         .await
     }
 
+    /// Find users where github_login ILIKE name_query.
     pub async fn fuzzy_search_users(&self, name_query: &str, limit: u32) -> Result<Vec<User>> {
         self.transaction(|tx| async {
             let tx = tx;
@@ -193,6 +203,8 @@ impl Database {
         .await
     }
 
+    /// fuzzy_like_string creates a string for matching in-order using fuzzy_search_users.
+    /// e.g. "cir" would become "%c%i%r%"
     pub fn fuzzy_like_string(string: &str) -> String {
         let mut result = String::with_capacity(string.len() * 2 + 1);
         for c in string.chars() {
@@ -205,6 +217,7 @@ impl Database {
         result
     }
 
+    /// Creates a new feature flag.
     pub async fn create_user_flag(&self, flag: &str) -> Result<FlagId> {
         self.transaction(|tx| async move {
             let flag = feature_flag::Entity::insert(feature_flag::ActiveModel {
@@ -220,6 +233,7 @@ impl Database {
         .await
     }
 
+    /// Add the given user to the feature flag
     pub async fn add_user_flag(&self, user: UserId, flag: FlagId) -> Result<()> {
         self.transaction(|tx| async move {
             user_feature::Entity::insert(user_feature::ActiveModel {
@@ -234,6 +248,7 @@ impl Database {
         .await
     }
 
+    /// Return the active flags for the user.
     pub async fn get_user_flags(&self, user: UserId) -> Result<Vec<String>> {
         self.transaction(|tx| async move {
             #[derive(Copy, Clone, Debug, EnumIter, DeriveColumn)]

crates/collab/src/db/tables/user.rs

@@ -2,6 +2,7 @@ use crate::db::UserId;
 use sea_orm::entity::prelude::*;
 use serde::Serialize;
 
+/// A user model.
 #[derive(Clone, Debug, Default, PartialEq, Eq, DeriveEntityModel, Serialize)]
 #[sea_orm(table_name = "users")]
 pub struct Model {

crates/collab/src/rpc.rs

@@ -932,11 +932,13 @@ async fn connection_lost(
     Ok(())
 }
 
+/// Acknowledges a ping from a client, used to keep the connection alive.
 async fn ping(_: proto::Ping, response: Response<proto::Ping>, _session: Session) -> Result<()> {
     response.send(proto::Ack {})?;
     Ok(())
 }
 
+/// Create a new room for calling (outside of channels)
 async fn create_room(
     _request: proto::CreateRoom,
     response: Response<proto::CreateRoom>,
@@ -984,6 +986,7 @@ async fn create_room(
     Ok(())
 }
 
+/// Join a room from an invitation. Equivalent to joining a channel if there is one.
 async fn join_room(
     request: proto::JoinRoom,
     response: Response<proto::JoinRoom>,
@@ -1058,6 +1061,7 @@ async fn join_room(
     Ok(())
 }
 
+/// Rejoin room is used to reconnect to a room after connection errors.
 async fn rejoin_room(
     request: proto::RejoinRoom,
     response: Response<proto::RejoinRoom>,
@@ -1249,6 +1253,7 @@ async fn rejoin_room(
     Ok(())
 }
 
+/// leave room disonnects from the room.
 async fn leave_room(
     _: proto::LeaveRoom,
     response: Response<proto::LeaveRoom>,
@@ -1259,6 +1264,7 @@ async fn leave_room(
     Ok(())
 }
 
+/// Update the permissions of someone else in the room.
 async fn set_room_participant_role(
     request: proto::SetRoomParticipantRole,
     response: Response<proto::SetRoomParticipantRole>,
@@ -1303,6 +1309,7 @@ async fn set_room_participant_role(
     Ok(())
 }
 
+/// Call someone else into the current room
 async fn call(
     request: proto::Call,
     response: Response<proto::Call>,
@@ -1371,6 +1378,7 @@ async fn call(
     Err(anyhow!("failed to ring user"))?
 }
 
+/// Cancel an outgoing call.
 async fn cancel_call(
     request: proto::CancelCall,
     response: Response<proto::CancelCall>,
@@ -1408,6 +1416,7 @@ async fn cancel_call(
     Ok(())
 }
 
+/// Decline an incoming call.
 async fn decline_call(message: proto::DeclineCall, session: Session) -> Result<()> {
     let room_id = RoomId::from_proto(message.room_id);
     {
@@ -1439,6 +1448,7 @@ async fn decline_call(message: proto::DeclineCall, session: Session) -> Result<(
     Ok(())
 }
 
+/// Update other participants in the room with your current location.
 async fn update_participant_location(
     request: proto::UpdateParticipantLocation,
     response: Response<proto::UpdateParticipantLocation>,
@@ -1459,6 +1469,7 @@ async fn update_participant_location(
     Ok(())
 }
 
+/// Share a project into the room.
 async fn share_project(
     request: proto::ShareProject,
     response: Response<proto::ShareProject>,
@@ -1481,6 +1492,7 @@ async fn share_project(
     Ok(())
 }
 
+/// Unshare a project from the room.
 async fn unshare_project(message: proto::UnshareProject, session: Session) -> Result<()> {
     let project_id = ProjectId::from_proto(message.project_id);
 
@@ -1500,6 +1512,7 @@ async fn unshare_project(message: proto::UnshareProject, session: Session) -> Re
     Ok(())
 }
 
+/// Join someone elses shared project.
 async fn join_project(
     request: proto::JoinProject,
     response: Response<proto::JoinProject>,
@@ -1625,6 +1638,7 @@ async fn join_project(
     Ok(())
 }
 
+/// Leave someone elses shared project.
 async fn leave_project(request: proto::LeaveProject, session: Session) -> Result<()> {
     let sender_id = session.connection_id;
     let project_id = ProjectId::from_proto(request.project_id);
@@ -1647,6 +1661,7 @@ async fn leave_project(request: proto::LeaveProject, session: Session) -> Result
     Ok(())
 }
 
+/// Update other participants with changes to the project
 async fn update_project(
     request: proto::UpdateProject,
     response: Response<proto::UpdateProject>,
@@ -1673,6 +1688,7 @@ async fn update_project(
     Ok(())
 }
 
+/// Update other participants with changes to the worktree
 async fn update_worktree(
     request: proto::UpdateWorktree,
     response: Response<proto::UpdateWorktree>,
@@ -1697,6 +1713,7 @@ async fn update_worktree(
     Ok(())
 }
 
+/// Update other participants with changes to the diagnostics
 async fn update_diagnostic_summary(
     message: proto::UpdateDiagnosticSummary,
     session: Session,
@@ -1720,6 +1737,7 @@ async fn update_diagnostic_summary(
     Ok(())
 }
 
+/// Update other participants with changes to the worktree settings
 async fn update_worktree_settings(
     message: proto::UpdateWorktreeSettings,
     session: Session,
@@ -1743,6 +1761,7 @@ async fn update_worktree_settings(
     Ok(())
 }
 
+/// Notify other participants that a  language server has started.
 async fn start_language_server(
     request: proto::StartLanguageServer,
     session: Session,
@@ -1765,6 +1784,7 @@ async fn start_language_server(
     Ok(())
 }
 
+/// Notify other participants that a language server has changed.
 async fn update_language_server(
     request: proto::UpdateLanguageServer,
     session: Session,
@@ -1787,6 +1807,8 @@ async fn update_language_server(
     Ok(())
 }
 
+/// forward a project request to the host. These requests should be read only
+/// as guests are allowed to send them.
 async fn forward_read_only_project_request<T>(
     request: T,
     response: Response<T>,
@@ -1809,6 +1831,8 @@ where
     Ok(())
 }
 
+/// forward a project request to the host. These requests are disallowed
+/// for guests.
 async fn forward_mutating_project_request<T>(
     request: T,
     response: Response<T>,
@@ -1831,6 +1855,7 @@ where
     Ok(())
 }
 
+/// Notify other participants that a new buffer has been created
 async fn create_buffer_for_peer(
     request: proto::CreateBufferForPeer,
     session: Session,
@@ -1850,6 +1875,8 @@ async fn create_buffer_for_peer(
     Ok(())
 }
 
+/// Notify other participants that a buffer has been updated. This is
+/// allowed for guests as long as the update is limited to selections.
 async fn update_buffer(
     request: proto::UpdateBuffer,
     response: Response<proto::UpdateBuffer>,
@@ -1909,6 +1936,7 @@ async fn update_buffer(
     Ok(())
 }
 
+/// Notify other participants that a project has been updated.
 async fn broadcast_project_message_from_host<T: EntityMessage<Entity = ShareProject>>(
     request: T,
     session: Session,
@@ -1932,6 +1960,7 @@ async fn broadcast_project_message_from_host<T: EntityMessage<Entity = ShareProj
     Ok(())
 }
 
+/// Start following another user in a call.
 async fn follow(
     request: proto::Follow,
     response: Response<proto::Follow>,
@@ -1969,6 +1998,7 @@ async fn follow(
     Ok(())
 }
 
+/// Stop following another user in a call.
 async fn unfollow(request: proto::Unfollow, session: Session) -> Result<()> {
     let room_id = RoomId::from_proto(request.room_id);
     let project_id = request.project_id.map(ProjectId::from_proto);
@@ -2000,6 +2030,7 @@ async fn unfollow(request: proto::Unfollow, session: Session) -> Result<()> {
     Ok(())
 }
 
+/// Notify everyone following you of your current location.
 async fn update_followers(request: proto::UpdateFollowers, session: Session) -> Result<()> {
     let room_id = RoomId::from_proto(request.room_id);
     let database = session.db.lock().await;
@@ -2036,6 +2067,7 @@ async fn update_followers(request: proto::UpdateFollowers, session: Session) ->
     Ok(())
 }
 
+/// Get public data about users.
 async fn get_users(
     request: proto::GetUsers,
     response: Response<proto::GetUsers>,
@@ -2062,6 +2094,7 @@ async fn get_users(
     Ok(())
 }
 
+/// Search for users (to invite) buy Github login
 async fn fuzzy_search_users(
     request: proto::FuzzySearchUsers,
     response: Response<proto::FuzzySearchUsers>,
@@ -2092,6 +2125,7 @@ async fn fuzzy_search_users(
     Ok(())
 }
 
+/// Send a contact request to another user.
 async fn request_contact(
     request: proto::RequestContact,
     response: Response<proto::RequestContact>,
@@ -2138,6 +2172,7 @@ async fn request_contact(
     Ok(())
 }
 
+/// Accept or decline a contact request
 async fn respond_to_contact_request(
     request: proto::RespondToContactRequest,
     response: Response<proto::RespondToContactRequest>,
@@ -2195,6 +2230,7 @@ async fn respond_to_contact_request(
     Ok(())
 }
 
+/// Remove a contact.
 async fn remove_contact(
     request: proto::RemoveContact,
     response: Response<proto::RemoveContact>,
@@ -2245,6 +2281,7 @@ async fn remove_contact(
     Ok(())
 }
 
+/// Create a new channel.
 async fn create_channel(
     request: proto::CreateChannel,
     response: Response<proto::CreateChannel>,
@@ -2279,6 +2316,7 @@ async fn create_channel(
     Ok(())
 }
 
+/// Delete a channel
 async fn delete_channel(
     request: proto::DeleteChannel,
     response: Response<proto::DeleteChannel>,
@@ -2308,6 +2346,7 @@ async fn delete_channel(
     Ok(())
 }
 
+/// Invite someone to join a channel.
 async fn invite_channel_member(
     request: proto::InviteChannelMember,
     response: Response<proto::InviteChannelMember>,
@@ -2344,6 +2383,7 @@ async fn invite_channel_member(
     Ok(())
 }
 
+/// remove someone from a channel
 async fn remove_channel_member(
     request: proto::RemoveChannelMember,
     response: Response<proto::RemoveChannelMember>,
@@ -2385,6 +2425,7 @@ async fn remove_channel_member(
     Ok(())
 }
 
+/// Toggle the channel between public and private
 async fn set_channel_visibility(
     request: proto::SetChannelVisibility,
     response: Response<proto::SetChannelVisibility>,
@@ -2423,6 +2464,7 @@ async fn set_channel_visibility(
     Ok(())
 }
 
+/// Alter the role for a user in the channel
 async fn set_channel_member_role(
     request: proto::SetChannelMemberRole,
     response: Response<proto::SetChannelMemberRole>,
@@ -2470,6 +2512,7 @@ async fn set_channel_member_role(
     Ok(())
 }
 
+/// Change the name of a channel
 async fn rename_channel(
     request: proto::RenameChannel,
     response: Response<proto::RenameChannel>,
@@ -2503,6 +2546,7 @@ async fn rename_channel(
     Ok(())
 }
 
+/// Move a channel to a new parent.
 async fn move_channel(
     request: proto::MoveChannel,
     response: Response<proto::MoveChannel>,
@@ -2555,6 +2599,7 @@ async fn notify_channel_moved(result: Option<MoveChannelResult>, session: Sessio
     Ok(())
 }
 
+/// Get the list of channel members
 async fn get_channel_members(
     request: proto::GetChannelMembers,
     response: Response<proto::GetChannelMembers>,
@@ -2569,6 +2614,7 @@ async fn get_channel_members(
     Ok(())
 }
 
+/// Accept or decline a channel invitation.
 async fn respond_to_channel_invite(
     request: proto::RespondToChannelInvite,
     response: Response<proto::RespondToChannelInvite>,
@@ -2609,6 +2655,7 @@ async fn respond_to_channel_invite(
     Ok(())
 }
 
+/// Join the channels' room
 async fn join_channel(
     request: proto::JoinChannel,
     response: Response<proto::JoinChannel>,
@@ -2713,6 +2760,7 @@ async fn join_channel_internal(
     Ok(())
 }
 
+/// Start editing the channel notes
 async fn join_channel_buffer(
     request: proto::JoinChannelBuffer,
     response: Response<proto::JoinChannelBuffer>,
@@ -2744,6 +2792,7 @@ async fn join_channel_buffer(
     Ok(())
 }
 
+/// Edit the channel notes
 async fn update_channel_buffer(
     request: proto::UpdateChannelBuffer,
     session: Session,
@@ -2790,6 +2839,7 @@ async fn update_channel_buffer(
     Ok(())
 }
 
+/// Rejoin the channel notes after a connection blip
 async fn rejoin_channel_buffers(
     request: proto::RejoinChannelBuffers,
     response: Response<proto::RejoinChannelBuffers>,
@@ -2824,6 +2874,7 @@ async fn rejoin_channel_buffers(
     Ok(())
 }
 
+/// Stop editing the channel notes
 async fn leave_channel_buffer(
     request: proto::LeaveChannelBuffer,
     response: Response<proto::LeaveChannelBuffer>,
@@ -2885,6 +2936,7 @@ fn send_notifications(
     }
 }
 
+/// Send a message to the channel
 async fn send_channel_message(
     request: proto::SendChannelMessage,
     response: Response<proto::SendChannelMessage>,
@@ -2973,6 +3025,7 @@ async fn send_channel_message(
     Ok(())
 }
 
+/// Delete a channel message
 async fn remove_channel_message(
     request: proto::RemoveChannelMessage,
     response: Response<proto::RemoveChannelMessage>,
@@ -2992,6 +3045,7 @@ async fn remove_channel_message(
     Ok(())
 }
 
+/// Mark a channel message as read
 async fn acknowledge_channel_message(
     request: proto::AckChannelMessage,
     session: Session,
@@ -3011,6 +3065,7 @@ async fn acknowledge_channel_message(
     Ok(())
 }
 
+/// Mark a buffer version as synced
 async fn acknowledge_buffer_version(
     request: proto::AckBufferOperation,
     session: Session,
@@ -3029,6 +3084,7 @@ async fn acknowledge_buffer_version(
     Ok(())
 }
 
+/// Start receiving chat updates for a channel
 async fn join_channel_chat(
     request: proto::JoinChannelChat,
     response: Response<proto::JoinChannelChat>,
@@ -3049,6 +3105,7 @@ async fn join_channel_chat(
     Ok(())
 }
 
+/// Stop receiving chat updates for a channel
 async fn leave_channel_chat(request: proto::LeaveChannelChat, session: Session) -> Result<()> {
     let channel_id = ChannelId::from_proto(request.channel_id);
     session
@@ -3059,6 +3116,7 @@ async fn leave_channel_chat(request: proto::LeaveChannelChat, session: Session)
     Ok(())
 }
 
+/// Retrive the chat history for a channel
 async fn get_channel_messages(
     request: proto::GetChannelMessages,
     response: Response<proto::GetChannelMessages>,
@@ -3082,6 +3140,7 @@ async fn get_channel_messages(
     Ok(())
 }
 
+/// Retrieve specific chat messages
 async fn get_channel_messages_by_id(
     request: proto::GetChannelMessagesById,
     response: Response<proto::GetChannelMessagesById>,
@@ -3104,6 +3163,7 @@ async fn get_channel_messages_by_id(
     Ok(())
 }
 
+/// Retrieve the current users notifications
 async fn get_notifications(
     request: proto::GetNotifications,
     response: Response<proto::GetNotifications>,
@@ -3127,6 +3187,7 @@ async fn get_notifications(
     Ok(())
 }
 
+/// Mark notifications as read
 async fn mark_notification_as_read(
     request: proto::MarkNotificationRead,
     response: Response<proto::MarkNotificationRead>,
@@ -3148,6 +3209,7 @@ async fn mark_notification_as_read(
     Ok(())
 }
 
+/// Get the current users information
 async fn get_private_user_info(
     _request: proto::GetPrivateUserInfo,
     response: Response<proto::GetPrivateUserInfo>,