Adding comments to all API related types. Fixes #2846 (#2848)

crates/api_common/src/comment.rs

@@ -14,11 +14,13 @@ use ts_rs::TS;
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Create a comment.
 pub struct CreateComment {
   pub content: String,
   pub post_id: PostId,
   pub parent_id: Option<CommentId>,
   pub language_id: Option<LanguageId>,
+  /// An optional front-end ID, to help UIs determine where the comment should go.
   pub form_id: Option<String>,
   pub auth: Sensitive<String>,
 }
@@ -27,6 +29,7 @@ pub struct CreateComment {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Fetch an individual comment.
 pub struct GetComment {
   pub id: CommentId,
   pub auth: Option<Sensitive<String>>,
@@ -36,6 +39,7 @@ pub struct GetComment {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Edit a comment.
 pub struct EditComment {
   pub comment_id: CommentId,
   pub content: Option<String>,
@@ -48,6 +52,7 @@ pub struct EditComment {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Distinguish a comment (IE speak as moderator).
 pub struct DistinguishComment {
   pub comment_id: CommentId,
   pub distinguished: bool,
@@ -58,6 +63,7 @@ pub struct DistinguishComment {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Delete your own comment.
 pub struct DeleteComment {
   pub comment_id: CommentId,
   pub deleted: bool,
@@ -68,6 +74,7 @@ pub struct DeleteComment {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Remove a comment (only doable by mods).
 pub struct RemoveComment {
   pub comment_id: CommentId,
   pub removed: bool,
@@ -78,6 +85,7 @@ pub struct RemoveComment {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Save / bookmark a comment.
 pub struct SaveComment {
   pub comment_id: CommentId,
   pub save: bool,
@@ -88,6 +96,7 @@ pub struct SaveComment {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A comment response.
 pub struct CommentResponse {
   pub comment_view: CommentView,
   pub recipient_ids: Vec<LocalUserId>,
@@ -98,8 +107,10 @@ pub struct CommentResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Like a comment.
 pub struct CreateCommentLike {
   pub comment_id: CommentId,
+  /// Must be -1, 0, or 1 .
   pub score: i16,
   pub auth: Sensitive<String>,
 }
@@ -108,6 +119,7 @@ pub struct CreateCommentLike {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Get a list of comments.
 pub struct GetComments {
   pub type_: Option<ListingType>,
   pub sort: Option<CommentSortType>,
@@ -125,6 +137,7 @@ pub struct GetComments {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The comment list response.
 pub struct GetCommentsResponse {
   pub comments: Vec<CommentView>,
 }
@@ -132,6 +145,7 @@ pub struct GetCommentsResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Report a comment.
 pub struct CreateCommentReport {
   pub comment_id: CommentId,
   pub reason: String,
@@ -141,6 +155,7 @@ pub struct CreateCommentReport {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The comment report response.
 pub struct CommentReportResponse {
   pub comment_report_view: CommentReportView,
 }
@@ -148,6 +163,7 @@ pub struct CommentReportResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Resolve a comment report (only doable by mods).
 pub struct ResolveCommentReport {
   pub report_id: CommentReportId,
   pub resolved: bool,
@@ -158,9 +174,9 @@ pub struct ResolveCommentReport {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// List comment reports.
 pub struct ListCommentReports {
   pub page: Option<i64>,
-
   pub limit: Option<i64>,
   /// Only shows the unresolved reports
   pub unresolved_only: Option<bool>,
@@ -172,6 +188,7 @@ pub struct ListCommentReports {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The comment report list response.
 pub struct ListCommentReportsResponse {
   pub comment_reports: Vec<CommentReportView>,
 }

crates/api_common/src/community.rs

@@ -15,6 +15,7 @@ use ts_rs::TS;
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Get a community. Must provide either an id, or a name.
 pub struct GetCommunity {
   pub id: Option<CommunityId>,
   /// Example: star_trek , or star_trek@xyz.tld
@@ -26,6 +27,7 @@ pub struct GetCommunity {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The community response.
 pub struct GetCommunityResponse {
   pub community_view: CommunityView,
   pub site: Option<Site>,
@@ -41,13 +43,21 @@ pub struct GetCommunityResponse {
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
+/// Create a community.
 pub struct CreateCommunity {
+  /// The unique name.
   pub name: String,
+  /// A longer title.
   pub title: String,
+  /// A longer sidebar, or description of your community, in markdown.
   pub description: Option<String>,
+  /// An icon URL.
   pub icon: Option<String>,
+  /// A banner URL.
   pub banner: Option<String>,
+  /// Whether its an NSFW community.
   pub nsfw: Option<bool>,
+  /// Whether to restrict posting only to moderators.
   pub posting_restricted_to_mods: Option<bool>,
   pub discussion_languages: Option<Vec<LanguageId>>,
   pub auth: Sensitive<String>,
@@ -56,6 +66,7 @@ pub struct CreateCommunity {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A simple community response.
 pub struct CommunityResponse {
   pub community_view: CommunityView,
   pub discussion_languages: Vec<LanguageId>,
@@ -65,6 +76,7 @@ pub struct CommunityResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Fetches a list of communities.
 pub struct ListCommunities {
   pub type_: Option<ListingType>,
   pub sort: Option<SortType>,
@@ -76,6 +88,7 @@ pub struct ListCommunities {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The response for listing communities.
 pub struct ListCommunitiesResponse {
   pub communities: Vec<CommunityView>,
 }
@@ -84,6 +97,7 @@ pub struct ListCommunitiesResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Ban a user from a community.
 pub struct BanFromCommunity {
   pub community_id: CommunityId,
   pub person_id: PersonId,
@@ -97,6 +111,7 @@ pub struct BanFromCommunity {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The response for banning a user from a community.
 pub struct BanFromCommunityResponse {
   pub person_view: PersonView,
   pub banned: bool,
@@ -105,6 +120,7 @@ pub struct BanFromCommunityResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Add a moderator to a community.
 pub struct AddModToCommunity {
   pub community_id: CommunityId,
   pub person_id: PersonId,
@@ -115,6 +131,7 @@ pub struct AddModToCommunity {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The response of adding a moderator to a community.
 pub struct AddModToCommunityResponse {
   pub moderators: Vec<CommunityModeratorView>,
 }
@@ -123,13 +140,20 @@ pub struct AddModToCommunityResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Edit a community.
 pub struct EditCommunity {
   pub community_id: CommunityId,
+  /// A longer title.
   pub title: Option<String>,
+  /// A longer sidebar, or description of your community, in markdown.
   pub description: Option<String>,
+  /// An icon URL.
   pub icon: Option<String>,
+  /// A banner URL.
   pub banner: Option<String>,
+  /// Whether its an NSFW community.
   pub nsfw: Option<bool>,
+  /// Whether to restrict posting only to moderators.
   pub posting_restricted_to_mods: Option<bool>,
   pub discussion_languages: Option<Vec<LanguageId>>,
   pub auth: Sensitive<String>,
@@ -139,6 +163,8 @@ pub struct EditCommunity {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Hide a community from the main view.
+// TODO this should really be a part of edit community. And why does it contain a reason, that should be in the mod tables.
 pub struct HideCommunity {
   pub community_id: CommunityId,
   pub hidden: bool,
@@ -150,6 +176,7 @@ pub struct HideCommunity {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Delete your own community.
 pub struct DeleteCommunity {
   pub community_id: CommunityId,
   pub deleted: bool,
@@ -160,6 +187,7 @@ pub struct DeleteCommunity {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Remove a community (only doable by moderators).
 pub struct RemoveCommunity {
   pub community_id: CommunityId,
   pub removed: bool,
@@ -171,6 +199,7 @@ pub struct RemoveCommunity {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Follow / subscribe to a community.
 pub struct FollowCommunity {
   pub community_id: CommunityId,
   pub follow: bool,
@@ -180,6 +209,7 @@ pub struct FollowCommunity {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Block a community.
 pub struct BlockCommunity {
   pub community_id: CommunityId,
   pub block: bool,
@@ -190,6 +220,7 @@ pub struct BlockCommunity {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The block community response.
 pub struct BlockCommunityResponse {
   pub community_view: CommunityView,
   pub blocked: bool,
@@ -198,6 +229,7 @@ pub struct BlockCommunityResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Transfer a community to a new owner.
 pub struct TransferCommunity {
   pub community_id: CommunityId,
   pub person_id: PersonId,

crates/api_common/src/custom_emoji.rs

@@ -9,6 +9,7 @@ use url::Url;
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Create a custom emoji.
 pub struct CreateCustomEmoji {
   pub category: String,
   pub shortcode: String,
@@ -22,6 +23,7 @@ pub struct CreateCustomEmoji {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Edit  a custom emoji.
 pub struct EditCustomEmoji {
   pub id: CustomEmojiId,
   pub category: String,
@@ -35,6 +37,7 @@ pub struct EditCustomEmoji {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Delete a custom emoji.
 pub struct DeleteCustomEmoji {
   pub id: CustomEmojiId,
   pub auth: Sensitive<String>,
@@ -43,6 +46,7 @@ pub struct DeleteCustomEmoji {
 #[derive(Serialize, Deserialize)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The response for deleting a custom emoji.
 pub struct DeleteCustomEmojiResponse {
   pub id: CustomEmojiId,
   pub success: bool,
@@ -51,6 +55,7 @@ pub struct DeleteCustomEmojiResponse {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A response for a custom emoji.
 pub struct CustomEmojiResponse {
   pub custom_emoji: CustomEmojiView,
 }

crates/api_common/src/person.rs

@@ -21,9 +21,11 @@ use ts_rs::TS;
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Logging into lemmy.
 pub struct Login {
   pub username_or_email: Sensitive<String>,
   pub password: Sensitive<String>,
+  /// May be required, if totp is enabled for their account.
   pub totp_2fa_token: Option<String>,
 }
 
@@ -31,6 +33,7 @@ pub struct Login {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Register / Sign up to lemmy.
 pub struct Register {
   pub username: String,
   pub password: Sensitive<String>,
@@ -38,8 +41,11 @@ pub struct Register {
   pub show_nsfw: bool,
   /// email is mandatory if email verification is enabled on the server
   pub email: Option<Sensitive<String>>,
+  /// The UUID of the captcha item.
   pub captcha_uuid: Option<String>,
+  /// Your captcha answer.
   pub captcha_answer: Option<String>,
+  /// A form field to trick signup bots. Should be None.
   pub honeypot: Option<String>,
   /// An answer is mandatory if require application is enabled on the server
   pub answer: Option<String>,
@@ -48,24 +54,29 @@ pub struct Register {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Fetches a Captcha item.
 pub struct GetCaptcha {}
 
 #[skip_serializing_none]
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A wrapper for the captcha response.
 pub struct GetCaptchaResponse {
-  pub ok: Option<CaptchaResponse>, // Will be None if captchas are disabled
+  /// Will be None if captchas are disabled.
+  pub ok: Option<CaptchaResponse>,
 }
 
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A captcha response.
 pub struct CaptchaResponse {
   /// A Base64 encoded png  
   pub png: String,
   /// A Base64 encoded wav audio  
   pub wav: String,
+  /// The UUID for the captcha item.
   pub uuid: String,
 }
 
@@ -73,27 +84,48 @@ pub struct CaptchaResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Saves settings for your user.
 pub struct SaveUserSettings {
+  /// Show nsfw posts.
   pub show_nsfw: Option<bool>,
+  /// Show post and comment scores.
   pub show_scores: Option<bool>,
+  /// Your user's theme.
   pub theme: Option<String>,
   pub default_sort_type: Option<SortType>,
   pub default_listing_type: Option<ListingType>,
+  /// The language of the lemmy interface
   pub interface_language: Option<String>,
+  /// A URL for your avatar.
   pub avatar: Option<String>,
+  /// A URL for your banner.
   pub banner: Option<String>,
+  /// Your display name, which can contain strange characters, and does not need to be unique.
   pub display_name: Option<String>,
+  /// Your email.
   pub email: Option<Sensitive<String>>,
+  /// Your bio / info, in markdown.
   pub bio: Option<String>,
+  /// Your matrix user id. Ex: @my_user:matrix.org  
   pub matrix_user_id: Option<String>,
+  /// Whether to show or hide avatars.
   pub show_avatars: Option<bool>,
+  /// Sends notifications to your email.
   pub send_notifications_to_email: Option<bool>,
+  /// Whether this account is a bot account. Users can hide these accounts easily if they wish.
   pub bot_account: Option<bool>,
+  /// Whether to show bot accounts.
   pub show_bot_accounts: Option<bool>,
+  /// Whether to show read posts.
   pub show_read_posts: Option<bool>,
+  /// Whether to show notifications for new posts.
+  // TODO notifs need to be reworked.
   pub show_new_post_notifs: Option<bool>,
+  /// A list of languages you are able to see discussion in.
   pub discussion_languages: Option<Vec<LanguageId>>,
-  /// None leaves it as is, true will generate or regenerate it, false clears it out
+  /// Generates a TOTP / 2-factor authentication token.
+  ///
+  /// None leaves it as is, true will generate or regenerate it, false clears it out.
   pub generate_totp_2fa: Option<bool>,
   pub auth: Sensitive<String>,
 }
@@ -101,6 +133,7 @@ pub struct SaveUserSettings {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Changes your account password.
 pub struct ChangePassword {
   pub new_password: Sensitive<String>,
   pub new_password_verify: Sensitive<String>,
@@ -112,10 +145,13 @@ pub struct ChangePassword {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A response for your login.
 pub struct LoginResponse {
   /// This is None in response to `Register` if email verification is enabled, or the server requires registration applications.
   pub jwt: Option<Sensitive<String>>,
+  /// If registration applications are required, this will return true for a signup response.
   pub registration_created: bool,
+  /// If email verifications are required, this will return true for a signup response.
   pub verify_email_sent: bool,
 }
 
@@ -123,8 +159,11 @@ pub struct LoginResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Gets a person's details.
+///
+/// Either person_id, or username are required.
 pub struct GetPersonDetails {
-  pub person_id: Option<PersonId>, // One of these two are required
+  pub person_id: Option<PersonId>,
   /// Example: dessalines , or dessalines@xyz.tld
   pub username: Option<String>,
   pub sort: Option<SortType>,
@@ -138,6 +177,7 @@ pub struct GetPersonDetails {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A person's details response.
 pub struct GetPersonDetailsResponse {
   pub person_view: PersonView,
   pub comments: Vec<CommentView>,
@@ -148,20 +188,7 @@ pub struct GetPersonDetailsResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
-pub struct GetRepliesResponse {
+/// Marks all notifications as read.
-  pub replies: Vec<CommentReplyView>,
-}
-
-#[derive(Debug, Serialize, Deserialize, Clone)]
-#[cfg_attr(feature = "full", derive(TS))]
-#[cfg_attr(feature = "full", ts(export))]
-pub struct GetPersonMentionsResponse {
-  pub mentions: Vec<PersonMentionView>,
-}
-
-#[derive(Debug, Serialize, Deserialize, Clone, Default)]
-#[cfg_attr(feature = "full", derive(TS))]
-#[cfg_attr(feature = "full", ts(export))]
 pub struct MarkAllAsRead {
   pub auth: Sensitive<String>,
 }
@@ -169,6 +196,7 @@ pub struct MarkAllAsRead {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Adds an admin to a site.
 pub struct AddAdmin {
   pub person_id: PersonId,
   pub added: bool,
@@ -178,6 +206,7 @@ pub struct AddAdmin {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The response of current admins.
 pub struct AddAdminResponse {
   pub admins: Vec<PersonView>,
 }
@@ -186,9 +215,11 @@ pub struct AddAdminResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Ban a person from the site.
 pub struct BanPerson {
   pub person_id: PersonId,
   pub ban: bool,
+  /// Optionally remove all their data. Useful for new troll accounts.
   pub remove_data: Option<bool>,
   pub reason: Option<String>,
   pub expires: Option<i64>,
@@ -198,6 +229,8 @@ pub struct BanPerson {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Get a list of banned persons.
+// TODO, this should be paged, since the list can be quite long.
 pub struct GetBannedPersons {
   pub auth: Sensitive<String>,
 }
@@ -205,6 +238,7 @@ pub struct GetBannedPersons {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The list of banned persons.
 pub struct BannedPersonsResponse {
   pub banned: Vec<PersonView>,
 }
@@ -212,6 +246,7 @@ pub struct BannedPersonsResponse {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A response for a banned person.
 pub struct BanPersonResponse {
   pub person_view: PersonView,
   pub banned: bool,
@@ -220,6 +255,7 @@ pub struct BanPersonResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Block a person.
 pub struct BlockPerson {
   pub person_id: PersonId,
   pub block: bool,
@@ -229,6 +265,7 @@ pub struct BlockPerson {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The response for a person block.
 pub struct BlockPersonResponse {
   pub person_view: PersonView,
   pub blocked: bool,
@@ -238,6 +275,7 @@ pub struct BlockPersonResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Get comment replies.
 pub struct GetReplies {
   pub sort: Option<CommentSortType>,
   pub page: Option<i64>,
@@ -246,10 +284,20 @@ pub struct GetReplies {
   pub auth: Sensitive<String>,
 }
 
+#[derive(Debug, Serialize, Deserialize, Clone, Default)]
+#[cfg_attr(feature = "full", derive(TS))]
+#[cfg_attr(feature = "full", ts(export))]
+/// Fetches your replies.
+// TODO, replies and mentions below should be redone as tagged enums.
+pub struct GetRepliesResponse {
+  pub replies: Vec<CommentReplyView>,
+}
+
 #[skip_serializing_none]
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Get mentions for your user.
 pub struct GetPersonMentions {
   pub sort: Option<CommentSortType>,
   pub page: Option<i64>,
@@ -258,9 +306,18 @@ pub struct GetPersonMentions {
   pub auth: Sensitive<String>,
 }
 
+#[derive(Debug, Serialize, Deserialize, Clone)]
+#[cfg_attr(feature = "full", derive(TS))]
+#[cfg_attr(feature = "full", ts(export))]
+/// The response of mentions for your user.
+pub struct GetPersonMentionsResponse {
+  pub mentions: Vec<PersonMentionView>,
+}
+
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Mark a person mention as read.
 pub struct MarkPersonMentionAsRead {
   pub person_mention_id: PersonMentionId,
   pub read: bool,
@@ -270,6 +327,7 @@ pub struct MarkPersonMentionAsRead {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The response for a person mention action.
 pub struct PersonMentionResponse {
   pub person_mention_view: PersonMentionView,
 }
@@ -277,6 +335,7 @@ pub struct PersonMentionResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Mark a comment reply as read.
 pub struct MarkCommentReplyAsRead {
   pub comment_reply_id: CommentReplyId,
   pub read: bool,
@@ -286,6 +345,7 @@ pub struct MarkCommentReplyAsRead {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The response for a comment reply action.
 pub struct CommentReplyResponse {
   pub comment_reply_view: CommentReplyView,
 }
@@ -293,6 +353,7 @@ pub struct CommentReplyResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Delete your account.
 pub struct DeleteAccount {
   pub password: Sensitive<String>,
   pub auth: Sensitive<String>,
@@ -301,11 +362,13 @@ pub struct DeleteAccount {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The response of deleting your account.
 pub struct DeleteAccountResponse {}
 
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Reset your password via email.
 pub struct PasswordReset {
   pub email: Sensitive<String>,
 }
@@ -313,11 +376,13 @@ pub struct PasswordReset {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The response of a password reset.
 pub struct PasswordResetResponse {}
 
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Change your password after receiving a reset request.
 pub struct PasswordChangeAfterReset {
   pub token: Sensitive<String>,
   pub password: Sensitive<String>,
@@ -328,6 +393,7 @@ pub struct PasswordChangeAfterReset {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Get a count of the number of reports.
 pub struct GetReportCount {
   pub community_id: Option<CommunityId>,
   pub auth: Sensitive<String>,
@@ -337,6 +403,7 @@ pub struct GetReportCount {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A response for the number of reports.
 pub struct GetReportCountResponse {
   pub community_id: Option<CommunityId>,
   pub comment_reports: i64,
@@ -347,6 +414,7 @@ pub struct GetReportCountResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Get a count of unread notifications.
 pub struct GetUnreadCount {
   pub auth: Sensitive<String>,
 }
@@ -354,6 +422,7 @@ pub struct GetUnreadCount {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A response containing counts for your notifications.
 pub struct GetUnreadCountResponse {
   pub replies: i64,
   pub mentions: i64,
@@ -363,6 +432,7 @@ pub struct GetUnreadCountResponse {
 #[derive(Serialize, Deserialize, Clone, Default, Debug)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Verify your email.
 pub struct VerifyEmail {
   pub token: String,
 }
@@ -370,4 +440,5 @@ pub struct VerifyEmail {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A response to verifying your email.
 pub struct VerifyEmailResponse {}

crates/api_common/src/post.rs

@@ -17,12 +17,15 @@ use url::Url;
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Create a post.
 pub struct CreatePost {
   pub name: String,
   pub community_id: CommunityId,
   #[cfg_attr(feature = "full", ts(type = "string"))]
   pub url: Option<Url>,
+  /// An optional body for the post in markdown.
   pub body: Option<String>,
+  /// A honeypot to catch bots. Should be None.
   pub honeypot: Option<String>,
   pub nsfw: Option<bool>,
   pub language_id: Option<LanguageId>,
@@ -40,6 +43,7 @@ pub struct PostResponse {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Get a post. Needs either the post id, or comment_id.
 pub struct GetPost {
   pub id: Option<PostId>,
   pub comment_id: Option<CommentId>,
@@ -49,10 +53,12 @@ pub struct GetPost {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The post response.
 pub struct GetPostResponse {
   pub post_view: PostView,
   pub community_view: CommunityView,
   pub moderators: Vec<CommunityModeratorView>,
+  /// A list of cross-posts, or other times / communities this link has been posted to.
   pub cross_posts: Vec<PostView>,
   pub online: usize,
 }
@@ -61,6 +67,7 @@ pub struct GetPostResponse {
 #[derive(Serialize, Deserialize, Debug, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Get a list of posts.
 pub struct GetPosts {
   pub type_: Option<ListingType>,
   pub sort: Option<SortType>,
@@ -75,6 +82,7 @@ pub struct GetPosts {
 #[derive(Serialize, Deserialize, Debug, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The post list response.
 pub struct GetPostsResponse {
   pub posts: Vec<PostView>,
 }
@@ -82,8 +90,10 @@ pub struct GetPostsResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Like a post.
 pub struct CreatePostLike {
   pub post_id: PostId,
+  /// Score must be -1, 0, or 1.
   pub score: i16,
   pub auth: Sensitive<String>,
 }
@@ -92,11 +102,13 @@ pub struct CreatePostLike {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Edit a post.
 pub struct EditPost {
   pub post_id: PostId,
   pub name: Option<String>,
   #[cfg_attr(feature = "full", ts(type = "string"))]
   pub url: Option<Url>,
+  /// An optional body for the post in markdown.
   pub body: Option<String>,
   pub nsfw: Option<bool>,
   pub language_id: Option<LanguageId>,
@@ -106,6 +118,7 @@ pub struct EditPost {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Delete a post.
 pub struct DeletePost {
   pub post_id: PostId,
   pub deleted: bool,
@@ -116,6 +129,7 @@ pub struct DeletePost {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Remove a post (only doable by mods).
 pub struct RemovePost {
   pub post_id: PostId,
   pub removed: bool,
@@ -126,6 +140,7 @@ pub struct RemovePost {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Mark a post as read.
 pub struct MarkPostAsRead {
   pub post_id: PostId,
   pub read: bool,
@@ -135,6 +150,7 @@ pub struct MarkPostAsRead {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Lock a post (prevent new comments).
 pub struct LockPost {
   pub post_id: PostId,
   pub locked: bool,
@@ -144,6 +160,7 @@ pub struct LockPost {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Feature a post (stickies / pins to the top).
 pub struct FeaturePost {
   pub post_id: PostId,
   pub featured: bool,
@@ -154,6 +171,7 @@ pub struct FeaturePost {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Save / bookmark a post.
 pub struct SavePost {
   pub post_id: PostId,
   pub save: bool,
@@ -163,6 +181,7 @@ pub struct SavePost {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Create a post report.
 pub struct CreatePostReport {
   pub post_id: PostId,
   pub reason: String,
@@ -172,6 +191,7 @@ pub struct CreatePostReport {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The post report response.
 pub struct PostReportResponse {
   pub post_report_view: PostReportView,
 }
@@ -179,6 +199,7 @@ pub struct PostReportResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Resolve a post report (mods only).
 pub struct ResolvePostReport {
   pub report_id: PostReportId,
   pub resolved: bool,
@@ -189,6 +210,7 @@ pub struct ResolvePostReport {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// List post reports.
 pub struct ListPostReports {
   pub page: Option<i64>,
   pub limit: Option<i64>,
@@ -202,6 +224,7 @@ pub struct ListPostReports {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The post reports response.
 pub struct ListPostReportsResponse {
   pub post_reports: Vec<PostReportView>,
 }
@@ -209,6 +232,7 @@ pub struct ListPostReportsResponse {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Get metadata for a given site.
 pub struct GetSiteMetadata {
   #[cfg_attr(feature = "full", ts(type = "string"))]
   pub url: Url,
@@ -217,6 +241,7 @@ pub struct GetSiteMetadata {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The site metadata response.
 pub struct GetSiteMetadataResponse {
   pub metadata: SiteMetadata,
 }
@@ -225,6 +250,7 @@ pub struct GetSiteMetadataResponse {
 #[derive(Debug, Deserialize, Serialize, PartialEq, Eq, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Site metadata, from its opengraph tags.
 pub struct SiteMetadata {
   pub title: Option<String>,
   pub description: Option<String>,

crates/api_common/src/private_message.rs

@@ -9,6 +9,7 @@ use ts_rs::TS;
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Create a private message.
 pub struct CreatePrivateMessage {
   pub content: String,
   pub recipient_id: PersonId,
@@ -18,6 +19,7 @@ pub struct CreatePrivateMessage {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Edit a private message.
 pub struct EditPrivateMessage {
   pub private_message_id: PrivateMessageId,
   pub content: String,
@@ -27,6 +29,7 @@ pub struct EditPrivateMessage {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Delete a private message.
 pub struct DeletePrivateMessage {
   pub private_message_id: PrivateMessageId,
   pub deleted: bool,
@@ -36,6 +39,7 @@ pub struct DeletePrivateMessage {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Mark a private message as read.
 pub struct MarkPrivateMessageAsRead {
   pub private_message_id: PrivateMessageId,
   pub read: bool,
@@ -46,6 +50,7 @@ pub struct MarkPrivateMessageAsRead {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Get your private messages.
 pub struct GetPrivateMessages {
   pub unread_only: Option<bool>,
   pub page: Option<i64>,
@@ -56,6 +61,7 @@ pub struct GetPrivateMessages {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The private messages response.
 pub struct PrivateMessagesResponse {
   pub private_messages: Vec<PrivateMessageView>,
 }
@@ -63,6 +69,7 @@ pub struct PrivateMessagesResponse {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A single private message response.
 pub struct PrivateMessageResponse {
   pub private_message_view: PrivateMessageView,
 }
@@ -70,6 +77,7 @@ pub struct PrivateMessageResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Create a report for a private message.
 pub struct CreatePrivateMessageReport {
   pub private_message_id: PrivateMessageId,
   pub reason: String,
@@ -79,6 +87,7 @@ pub struct CreatePrivateMessageReport {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A private message report response.
 pub struct PrivateMessageReportResponse {
   pub private_message_report_view: PrivateMessageReportView,
 }
@@ -86,6 +95,7 @@ pub struct PrivateMessageReportResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Resolve a private message report.
 pub struct ResolvePrivateMessageReport {
   pub report_id: PrivateMessageReportId,
   pub resolved: bool,
@@ -96,6 +106,8 @@ pub struct ResolvePrivateMessageReport {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// List private message reports.
+// TODO , perhaps GetReports should be a tagged enum list too.
 pub struct ListPrivateMessageReports {
   pub page: Option<i64>,
   pub limit: Option<i64>,
@@ -107,6 +119,7 @@ pub struct ListPrivateMessageReports {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The response for list private message reports.
 pub struct ListPrivateMessageReportsResponse {
   pub private_message_reports: Vec<PrivateMessageReportView>,
 }

crates/api_common/src/sensitive.rs

@@ -3,7 +3,6 @@ use std::{
   borrow::Borrow,
   ops::{Deref, DerefMut},
 };
-
 #[cfg(feature = "full")]
 use ts_rs::TS;
 

crates/api_common/src/site.rs

@@ -50,6 +50,7 @@ use ts_rs::TS;
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Searches the site, given a query string, and some optional filters.
 pub struct Search {
   pub q: String,
   pub community_id: Option<CommunityId>,
@@ -66,6 +67,8 @@ pub struct Search {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The search response, containing lists of the return type possibilities
+// TODO this should be redone as a list of tagged enums
 pub struct SearchResponse {
   pub type_: SearchType,
   pub comments: Vec<CommentView>,
@@ -77,7 +80,9 @@ pub struct SearchResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Does an apub fetch for an object.
 pub struct ResolveObject {
+  /// Can be the full url, or a shortened version like: !fediverse@lemmy.ml
   pub q: String,
   pub auth: Sensitive<String>,
 }
@@ -87,6 +92,7 @@ pub struct ResolveObject {
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
 // TODO Change this to an enum
+/// The response of an apub object fetch.
 pub struct ResolveObjectResponse {
   pub comment: Option<CommentView>,
   pub post: Option<PostView>,
@@ -98,6 +104,7 @@ pub struct ResolveObjectResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Fetches the modlog.
 pub struct GetModlog {
   pub mod_person_id: Option<PersonId>,
   pub community_id: Option<CommunityId>,
@@ -111,6 +118,8 @@ pub struct GetModlog {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The modlog fetch response.
+// TODO this should be redone as a list of tagged enums
 pub struct GetModlogResponse {
   pub removed_posts: Vec<ModRemovePostView>,
   pub locked_posts: Vec<ModLockPostView>,
@@ -133,6 +142,7 @@ pub struct GetModlogResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Creates a site. Should be done after first running lemmy.
 pub struct CreateSite {
   pub name: String,
   pub sidebar: Option<String>,
@@ -181,47 +191,79 @@ pub struct CreateSite {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Edits a site.
 pub struct EditSite {
   pub name: Option<String>,
   pub sidebar: Option<String>,
+  /// A shorter, one line description of your site.
   pub description: Option<String>,
+  /// A url for your site's icon.
   pub icon: Option<String>,
+  /// A url for your site's banner.
   pub banner: Option<String>,
+  /// Whether to enable downvotes.
   pub enable_downvotes: Option<bool>,
+  /// Whether to enable NSFW.
   pub enable_nsfw: Option<bool>,
+  /// Limits community creation to admins only.
   pub community_creation_admin_only: Option<bool>,
+  /// Whether to require email verification.
   pub require_email_verification: Option<bool>,
+  /// Your application question form. This is in markdown, and can be many questions.
   pub application_question: Option<String>,
+  /// Whether your instance is public, or private.
   pub private_instance: Option<bool>,
+  /// The default theme. Usually "browser"
   pub default_theme: Option<String>,
   pub default_post_listing_type: Option<ListingType>,
+  /// An optional page of legal information
   pub legal_information: Option<String>,
+  /// Whether to email admins when receiving a new application.
   pub application_email_admins: Option<bool>,
+  /// Whether to hide moderator names from the modlog.
   pub hide_modlog_mod_names: Option<bool>,
+  /// A list of allowed discussion languages.
   pub discussion_languages: Option<Vec<LanguageId>>,
+  /// A regex string of items to filter.
   pub slur_filter_regex: Option<String>,
+  /// The max length of actor names.
   pub actor_name_max_length: Option<i32>,
+  /// The number of messages allowed in a given time frame.
   pub rate_limit_message: Option<i32>,
   pub rate_limit_message_per_second: Option<i32>,
+  /// The number of posts allowed in a given time frame.
   pub rate_limit_post: Option<i32>,
   pub rate_limit_post_per_second: Option<i32>,
+  /// The number of registrations allowed in a given time frame.
   pub rate_limit_register: Option<i32>,
   pub rate_limit_register_per_second: Option<i32>,
+  /// The number of image uploads allowed in a given time frame.
   pub rate_limit_image: Option<i32>,
   pub rate_limit_image_per_second: Option<i32>,
+  /// The number of comments allowed in a given time frame.
   pub rate_limit_comment: Option<i32>,
   pub rate_limit_comment_per_second: Option<i32>,
+  /// The number of searches allowed in a given time frame.
   pub rate_limit_search: Option<i32>,
   pub rate_limit_search_per_second: Option<i32>,
+  /// Whether to enable federation.
   pub federation_enabled: Option<bool>,
+  /// Enables federation debugging.
   pub federation_debug: Option<bool>,
+  /// The number of federation workers.
   pub federation_worker_count: Option<i32>,
+  /// Whether to enable captchas for signups.
   pub captcha_enabled: Option<bool>,
+  /// The captcha difficulty. Can be easy, medium, or hard
   pub captcha_difficulty: Option<String>,
+  /// A list of allowed instances. If none are set, federation is open.
   pub allowed_instances: Option<Vec<String>>,
+  /// A list of blocked instances.
   pub blocked_instances: Option<Vec<String>>,
+  /// A list of taglines shown at the top of the front page.
   pub taglines: Option<Vec<String>>,
   pub registration_mode: Option<RegistrationMode>,
+  /// Whether to email admins for new reports.
   pub reports_email_admins: Option<bool>,
   pub auth: Sensitive<String>,
 }
@@ -230,6 +272,7 @@ pub struct EditSite {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Fetches the site.
 pub struct GetSite {
   pub auth: Option<Sensitive<String>>,
 }
@@ -237,6 +280,7 @@ pub struct GetSite {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The response for a site.
 pub struct SiteResponse {
   pub site_view: SiteView,
 }
@@ -245,6 +289,7 @@ pub struct SiteResponse {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// An expanded response for a site.
 pub struct GetSiteResponse {
   pub site_view: SiteView,
   pub admins: Vec<PersonView>,
@@ -253,26 +298,32 @@ pub struct GetSiteResponse {
   pub my_user: Option<MyUserInfo>,
   pub all_languages: Vec<Language>,
   pub discussion_languages: Vec<LanguageId>,
+  /// A list of taglines shown at the top of the front page.
   pub taglines: Vec<Tagline>,
+  /// A list of custom emojis your site supports.
   pub custom_emojis: Vec<CustomEmojiView>,
 }
 
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Fetches the federated instances for your site.
 pub struct GetFederatedInstances {}
 
 #[skip_serializing_none]
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A response of federated instances.
 pub struct GetFederatedInstancesResponse {
-  pub federated_instances: Option<FederatedInstances>, // Federation may be disabled
+  /// Optional, because federation may be disabled.
+  pub federated_instances: Option<FederatedInstances>,
 }
 
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Your user info.
 pub struct MyUserInfo {
   pub local_user_view: LocalUserView,
   pub follows: Vec<CommunityFollowerView>,
@@ -285,6 +336,7 @@ pub struct MyUserInfo {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Leaves the admin team.
 pub struct LeaveAdmin {
   pub auth: Sensitive<String>,
 }
@@ -292,6 +344,7 @@ pub struct LeaveAdmin {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A list of federated instances.
 pub struct FederatedInstances {
   pub linked: Vec<Instance>,
   pub allowed: Vec<Instance>,
@@ -302,6 +355,7 @@ pub struct FederatedInstances {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Purges a person from the database. This will delete all content attached to that person.
 pub struct PurgePerson {
   pub person_id: PersonId,
   pub reason: Option<String>,
@@ -312,6 +366,7 @@ pub struct PurgePerson {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Purges a community from the database. This will delete all content attached to that community.
 pub struct PurgeCommunity {
   pub community_id: CommunityId,
   pub reason: Option<String>,
@@ -322,6 +377,7 @@ pub struct PurgeCommunity {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Purges a post from the database. This will delete all content attached to that post.
 pub struct PurgePost {
   pub post_id: PostId,
   pub reason: Option<String>,
@@ -332,6 +388,7 @@ pub struct PurgePost {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Purges a comment from the database. This will delete all content attached to that comment.
 pub struct PurgeComment {
   pub comment_id: CommentId,
   pub reason: Option<String>,
@@ -341,6 +398,7 @@ pub struct PurgeComment {
 #[derive(Serialize, Deserialize)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The response for purged items.
 pub struct PurgeItemResponse {
   pub success: bool,
 }
@@ -349,6 +407,7 @@ pub struct PurgeItemResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Fetches a list of registration applications.
 pub struct ListRegistrationApplications {
   /// Only shows the unread applications (IE those without an admin actor)
   pub unread_only: Option<bool>,
@@ -360,6 +419,7 @@ pub struct ListRegistrationApplications {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The list of registration applications.
 pub struct ListRegistrationApplicationsResponse {
   pub registration_applications: Vec<RegistrationApplicationView>,
 }
@@ -368,6 +428,7 @@ pub struct ListRegistrationApplicationsResponse {
 #[derive(Debug, Serialize, Deserialize, Clone, Default)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Approves a registration application.
 pub struct ApproveRegistrationApplication {
   pub id: i32,
   pub approve: bool,
@@ -378,6 +439,7 @@ pub struct ApproveRegistrationApplication {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The response of an action done to a registration application.
 pub struct RegistrationApplicationResponse {
   pub registration_application: RegistrationApplicationView,
 }
@@ -385,6 +447,7 @@ pub struct RegistrationApplicationResponse {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Gets a count of unread registration applications.
 pub struct GetUnreadRegistrationApplicationCount {
   pub auth: Sensitive<String>,
 }
@@ -392,6 +455,7 @@ pub struct GetUnreadRegistrationApplicationCount {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The count of unread registration applications.
 pub struct GetUnreadRegistrationApplicationCountResponse {
   pub registration_applications: i64,
 }

crates/api_common/src/websocket/structs.rs

@@ -7,6 +7,7 @@ use ts_rs::TS;
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Join a user room.
 pub struct UserJoin {
   pub auth: Sensitive<String>,
 }
@@ -14,6 +15,7 @@ pub struct UserJoin {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The join response.
 pub struct UserJoinResponse {
   pub joined: bool,
 }
@@ -21,6 +23,7 @@ pub struct UserJoinResponse {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Join a community room.
 pub struct CommunityJoin {
   pub community_id: CommunityId,
 }
@@ -28,6 +31,7 @@ pub struct CommunityJoin {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The join response.
 pub struct CommunityJoinResponse {
   pub joined: bool,
 }
@@ -35,6 +39,7 @@ pub struct CommunityJoinResponse {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Join a mod room.
 pub struct ModJoin {
   pub community_id: CommunityId,
 }
@@ -42,6 +47,7 @@ pub struct ModJoin {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The join response.
 pub struct ModJoinResponse {
   pub joined: bool,
 }
@@ -49,6 +55,7 @@ pub struct ModJoinResponse {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Join a post room.
 pub struct PostJoin {
   pub post_id: PostId,
 }
@@ -56,6 +63,7 @@ pub struct PostJoin {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The join response.
 pub struct PostJoinResponse {
   pub joined: bool,
 }

crates/db_schema/src/aggregates/structs.rs

@@ -17,6 +17,7 @@ use ts_rs::TS;
 #[cfg_attr(feature = "full", diesel(table_name = comment_aggregates))]
 #[cfg_attr(feature = "full", diesel(belongs_to(crate::source::comment::Comment)))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Aggregate data for a comment.
 pub struct CommentAggregates {
   pub id: i32,
   pub comment_id: CommentId,
@@ -24,6 +25,7 @@ pub struct CommentAggregates {
   pub upvotes: i64,
   pub downvotes: i64,
   pub published: chrono::NaiveDateTime,
+  /// The total number of children in this comment branch.
   pub child_count: i32,
 }
 
@@ -35,6 +37,7 @@ pub struct CommentAggregates {
   diesel(belongs_to(crate::source::community::Community))
 )]
 #[cfg_attr(feature = "full", ts(export))]
+/// Aggregate data for a community.
 pub struct CommunityAggregates {
   pub id: i32,
   pub community_id: CommunityId,
@@ -42,9 +45,13 @@ pub struct CommunityAggregates {
   pub posts: i64,
   pub comments: i64,
   pub published: chrono::NaiveDateTime,
+  /// The number of users with any activity in the last day.
   pub users_active_day: i64,
+  /// The number of users with any activity in the last week.
   pub users_active_week: i64,
+  /// The number of users with any activity in the last month.
   pub users_active_month: i64,
+  /// The number of users with any activity in the last year.
   pub users_active_half_year: i64,
 }
 
@@ -53,6 +60,7 @@ pub struct CommunityAggregates {
 #[cfg_attr(feature = "full", diesel(table_name = person_aggregates))]
 #[cfg_attr(feature = "full", diesel(belongs_to(crate::source::person::Person)))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Aggregate data for a person.
 pub struct PersonAggregates {
   pub id: i32,
   pub person_id: PersonId,
@@ -67,6 +75,7 @@ pub struct PersonAggregates {
 #[cfg_attr(feature = "full", diesel(table_name = post_aggregates))]
 #[cfg_attr(feature = "full", diesel(belongs_to(crate::source::post::Post)))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Aggregate data for a post.
 pub struct PostAggregates {
   pub id: i32,
   pub post_id: PostId,
@@ -75,9 +84,13 @@ pub struct PostAggregates {
   pub upvotes: i64,
   pub downvotes: i64,
   pub published: chrono::NaiveDateTime,
-  pub newest_comment_time_necro: chrono::NaiveDateTime, // A newest comment time, limited to 2 days, to prevent necrobumping
+  /// A newest comment time, limited to 2 days, to prevent necrobumping  
+  pub newest_comment_time_necro: chrono::NaiveDateTime,
+  /// The time of the newest comment in the post.
   pub newest_comment_time: chrono::NaiveDateTime,
+  /// If the post is featured on the community.
   pub featured_community: bool,
+  /// If the post is featured on the site / to local.
   pub featured_local: bool,
 }
 
@@ -85,10 +98,14 @@ pub struct PostAggregates {
 #[cfg_attr(feature = "full", derive(Queryable, Associations, Identifiable))]
 #[cfg_attr(feature = "full", diesel(table_name = person_post_aggregates))]
 #[cfg_attr(feature = "full", diesel(belongs_to(crate::source::person::Person)))]
+/// Aggregate data for a person's post.
 pub struct PersonPostAggregates {
   pub id: i32,
   pub person_id: PersonId,
   pub post_id: PostId,
+  /// The number of comments they've read on that post.
+  ///
+  /// This is updated to the current post comment count every time they view a post.
   pub read_comments: i64,
   pub published: chrono::NaiveDateTime,
 }
@@ -108,6 +125,7 @@ pub struct PersonPostAggregatesForm {
 #[cfg_attr(feature = "full", diesel(table_name = site_aggregates))]
 #[cfg_attr(feature = "full", diesel(belongs_to(crate::source::site::Site)))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Aggregate data for a site.
 pub struct SiteAggregates {
   pub id: i32,
   pub site_id: SiteId,
@@ -115,8 +133,12 @@ pub struct SiteAggregates {
   pub posts: i64,
   pub comments: i64,
   pub communities: i64,
+  /// The number of users with any activity in the last day.
   pub users_active_day: i64,
+  /// The number of users with any activity in the last week.
   pub users_active_week: i64,
+  /// The number of users with any activity in the last month.
   pub users_active_month: i64,
+  /// The number of users with any activity in the last half year.
   pub users_active_half_year: i64,
 }

crates/db_schema/src/lib.rs

@@ -46,6 +46,7 @@ use ts_rs::TS;
 )]
 #[cfg_attr(feature = "full", DbValueStyle = "verbatim")]
 #[cfg_attr(feature = "full", ts(export))]
+/// The post sort types. See here for descriptions: https://join-lemmy.org/docs/en/users/03-votes-and-ranking.html
 pub enum SortType {
   Active,
   Hot,
@@ -63,6 +64,7 @@ pub enum SortType {
 #[derive(EnumString, Display, Debug, Serialize, Deserialize, Clone, Copy)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The comment sort types. See here for descriptions: https://join-lemmy.org/docs/en/users/03-votes-and-ranking.html
 pub enum CommentSortType {
   Hot,
   Top,
@@ -78,9 +80,13 @@ pub enum CommentSortType {
 )]
 #[cfg_attr(feature = "full", DbValueStyle = "verbatim")]
 #[cfg_attr(feature = "full", ts(export))]
+/// A listing type for post and comment list fetches.
 pub enum ListingType {
+  /// Content from your own site, as well as all connected / federated sites.
   All,
+  /// Content from your site only.
   Local,
+  /// Content only from communities you've subscribed to.
   Subscribed,
 }
 
@@ -92,15 +98,20 @@ pub enum ListingType {
 )]
 #[cfg_attr(feature = "full", DbValueStyle = "verbatim")]
 #[cfg_attr(feature = "full", ts(export))]
+/// The registration mode for your site. Determines what happens after a user signs up.
 pub enum RegistrationMode {
+  /// Closed to public.
   Closed,
+  /// Open, but pending approval of a registration application.
   RequireApplication,
+  /// Open to all.
   Open,
 }
 
 #[derive(EnumString, Display, Debug, Serialize, Deserialize, Clone, Copy)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The type of content returned from a search.
 pub enum SearchType {
   All,
   Comments,
@@ -113,6 +124,7 @@ pub enum SearchType {
 #[derive(EnumString, Display, Debug, PartialEq, Eq, Serialize, Deserialize, Clone, Copy)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A type / status for a community subscribe.
 pub enum SubscribedType {
   Subscribed,
   NotSubscribed,
@@ -122,6 +134,7 @@ pub enum SubscribedType {
 #[derive(EnumString, Display, Debug, Serialize, Deserialize, Clone, Copy, PartialEq, Eq)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A list of possible types for the various modlog actions.
 pub enum ModlogActionType {
   All,
   ModRemovePost,
@@ -146,8 +159,11 @@ pub enum ModlogActionType {
 )]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The feature type for a post.
 pub enum PostFeatureType {
   #[default]
+  /// Features to the top of your site.
   Local,
+  /// Features to the top of the community.
   Community,
 }

crates/db_schema/src/newtypes.rs

@@ -20,6 +20,7 @@ use url::Url;
 #[derive(Debug, Copy, Clone, Hash, Eq, PartialEq, Default, Serialize, Deserialize)]
 #[cfg_attr(feature = "full", derive(DieselNewType, TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The post id.
 pub struct PostId(pub i32);
 
 impl fmt::Display for PostId {
@@ -31,11 +32,13 @@ impl fmt::Display for PostId {
 #[derive(Debug, Copy, Clone, Hash, Eq, PartialEq, Default, Serialize, Deserialize)]
 #[cfg_attr(feature = "full", derive(DieselNewType, TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The person id.
 pub struct PersonId(pub i32);
 
 #[derive(Debug, Copy, Clone, Hash, Eq, PartialEq, Serialize, Deserialize, Default)]
 #[cfg_attr(feature = "full", derive(DieselNewType, TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The comment id.
 pub struct CommentId(pub i32);
 
 impl fmt::Display for CommentId {
@@ -47,16 +50,19 @@ impl fmt::Display for CommentId {
 #[derive(Debug, Copy, Clone, Hash, Eq, PartialEq, Default, Serialize, Deserialize)]
 #[cfg_attr(feature = "full", derive(DieselNewType, TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The community id.
 pub struct CommunityId(pub i32);
 
 #[derive(Debug, Copy, Clone, Hash, Eq, PartialEq, Default, Serialize, Deserialize)]
 #[cfg_attr(feature = "full", derive(DieselNewType, TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The local user id.
 pub struct LocalUserId(pub i32);
 
 #[derive(Debug, Copy, Clone, Hash, Eq, PartialEq, Serialize, Deserialize, Default)]
 #[cfg_attr(feature = "full", derive(DieselNewType, TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The private message id.
 pub struct PrivateMessageId(i32);
 
 impl fmt::Display for PrivateMessageId {
@@ -68,41 +74,49 @@ impl fmt::Display for PrivateMessageId {
 #[derive(Debug, Copy, Clone, Hash, Eq, PartialEq, Serialize, Deserialize, Default)]
 #[cfg_attr(feature = "full", derive(DieselNewType, TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The person mention id.
 pub struct PersonMentionId(i32);
 
 #[derive(Debug, Copy, Clone, Hash, Eq, PartialEq, Serialize, Deserialize, Default)]
 #[cfg_attr(feature = "full", derive(DieselNewType, TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The person block id.
 pub struct PersonBlockId(i32);
 
 #[derive(Debug, Copy, Clone, Hash, Eq, PartialEq, Serialize, Deserialize, Default)]
 #[cfg_attr(feature = "full", derive(DieselNewType, TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The community block id.
 pub struct CommunityBlockId(i32);
 
 #[derive(Debug, Copy, Clone, Hash, Eq, PartialEq, Serialize, Deserialize, Default)]
 #[cfg_attr(feature = "full", derive(DieselNewType, TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The comment report id.
 pub struct CommentReportId(i32);
 
 #[derive(Debug, Copy, Clone, Hash, Eq, PartialEq, Serialize, Deserialize, Default)]
 #[cfg_attr(feature = "full", derive(DieselNewType, TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The post report id.
 pub struct PostReportId(i32);
 
 #[derive(Debug, Copy, Clone, Hash, Eq, PartialEq, Serialize, Deserialize, Default)]
 #[cfg_attr(feature = "full", derive(DieselNewType, TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The private message report id.
 pub struct PrivateMessageReportId(i32);
 
 #[derive(Debug, Copy, Clone, Hash, Eq, PartialEq, Serialize, Deserialize, Default)]
 #[cfg_attr(feature = "full", derive(DieselNewType, TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The site id.
 pub struct SiteId(i32);
 
 #[derive(Debug, Copy, Clone, Hash, Eq, PartialEq, Serialize, Deserialize, Default)]
 #[cfg_attr(feature = "full", derive(DieselNewType, TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The language id.
 pub struct LanguageId(pub i32);
 
 #[derive(Debug, Copy, Clone, Hash, Eq, PartialEq, Serialize, Deserialize, Default)]
@@ -120,21 +134,25 @@ pub struct CommunityLanguageId(pub i32);
 #[derive(Debug, Copy, Clone, Hash, Eq, PartialEq, Serialize, Deserialize, Default)]
 #[cfg_attr(feature = "full", derive(DieselNewType, TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The comment reply id.
 pub struct CommentReplyId(i32);
 
 #[derive(Debug, Copy, Clone, Hash, Eq, PartialEq, Serialize, Deserialize, Default)]
 #[cfg_attr(feature = "full", derive(DieselNewType, TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The instance id.
 pub struct InstanceId(i32);
 
 #[derive(Debug, Copy, Clone, Hash, Eq, PartialEq, Serialize, Deserialize, Default)]
 #[cfg_attr(feature = "full", derive(DieselNewType, TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The local site id.
 pub struct LocalSiteId(i32);
 
 #[derive(Debug, Copy, Clone, Hash, Eq, PartialEq, Serialize, Deserialize, Default)]
 #[cfg_attr(feature = "full", derive(DieselNewType, TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The custom emoji id.
 pub struct CustomEmojiId(i32);
 
 #[cfg(feature = "full")]

crates/db_schema/src/source/comment.rs

@@ -17,21 +17,28 @@ use typed_builder::TypedBuilder;
 #[cfg_attr(feature = "full", ts(export))]
 #[cfg_attr(feature = "full", diesel(belongs_to(crate::source::post::Post)))]
 #[cfg_attr(feature = "full", diesel(table_name = comment))]
+/// A comment.
 pub struct Comment {
   pub id: CommentId,
   pub creator_id: PersonId,
   pub post_id: PostId,
   pub content: String,
+  /// Whether the comment has been removed.
   pub removed: bool,
   pub published: chrono::NaiveDateTime,
   pub updated: Option<chrono::NaiveDateTime>,
+  /// Whether the comment has been deleted by its creator.
   pub deleted: bool,
+  /// The federated activity id / ap_id.
   pub ap_id: DbUrl,
+  /// Whether the comment is local.
   pub local: bool,
   #[cfg(feature = "full")]
   #[cfg_attr(feature = "full", serde(with = "LtreeDef"))]
   #[cfg_attr(feature = "full", ts(type = "string"))]
+  /// The path / tree location of a comment, separated by dots, ending with the comment's id. Ex: 0.24.27
   pub path: Ltree,
+  /// Whether the comment has been distinguished(speaking officially) by a mod.
   pub distinguished: bool,
   pub language_id: LanguageId,
 }

crates/db_schema/src/source/comment_reply.rs

@@ -10,7 +10,7 @@ use ts_rs::TS;
 #[cfg_attr(feature = "full", diesel(belongs_to(crate::source::comment::Comment)))]
 #[cfg_attr(feature = "full", diesel(table_name = comment_reply))]
 #[cfg_attr(feature = "full", ts(export))]
-/// This table keeps a list of replies to comments and posts.
+/// A comment reply.
 pub struct CommentReply {
   pub id: CommentReplyId,
   pub recipient_id: PersonId,

crates/db_schema/src/source/comment_report.rs

@@ -12,6 +12,7 @@ use ts_rs::TS;
 #[cfg_attr(feature = "full", diesel(belongs_to(crate::source::comment::Comment)))]
 #[cfg_attr(feature = "full", diesel(table_name = comment_report))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A comment report.
 pub struct CommentReport {
   pub id: CommentReportId,
   pub creator_id: PersonId,

crates/db_schema/src/source/community.rs

@@ -12,17 +12,25 @@ use typed_builder::TypedBuilder;
 #[cfg_attr(feature = "full", derive(Queryable, Identifiable, TS))]
 #[cfg_attr(feature = "full", diesel(table_name = community))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A community.
 pub struct Community {
   pub id: CommunityId,
   pub name: String,
+  /// A longer title, that can contain other characters, and doesn't have to be unique.
   pub title: String,
+  /// A sidebar / markdown description.
   pub description: Option<String>,
+  /// Whether the community is removed by a mod.
   pub removed: bool,
   pub published: chrono::NaiveDateTime,
   pub updated: Option<chrono::NaiveDateTime>,
+  /// Whether the community has been deleted by its creator.
   pub deleted: bool,
+  /// Whether its an NSFW community.
   pub nsfw: bool,
+  /// The federated actor_id.
   pub actor_id: DbUrl,
+  /// Whether the community is local.
   pub local: bool,
   #[serde(skip)]
   pub private_key: Option<String>,
@@ -30,7 +38,9 @@ pub struct Community {
   pub public_key: String,
   #[serde(skip)]
   pub last_refreshed_at: chrono::NaiveDateTime,
+  /// A URL for an icon.
   pub icon: Option<DbUrl>,
+  /// A URL for a banner.
   pub banner: Option<DbUrl>,
   #[serde(skip_serializing)]
   pub followers_url: DbUrl,
@@ -38,7 +48,9 @@ pub struct Community {
   pub inbox_url: DbUrl,
   #[serde(skip)]
   pub shared_inbox_url: Option<DbUrl>,
+  /// Whether the community is hidden.
   pub hidden: bool,
+  /// Whether posting is restricted to mods only.
   pub posting_restricted_to_mods: bool,
   pub instance_id: InstanceId,
   /// Url where moderators collection is served over Activitypub

crates/db_schema/src/source/custom_emoji.rs

@@ -16,6 +16,7 @@ use typed_builder::TypedBuilder;
   diesel(belongs_to(crate::source::local_site::LocalSite))
 )]
 #[cfg_attr(feature = "full", ts(export))]
+/// A custom emoji.
 pub struct CustomEmoji {
   pub id: CustomEmojiId,
   pub local_site_id: LocalSiteId,

crates/db_schema/src/source/custom_emoji_keyword.rs

@@ -14,6 +14,7 @@ use typed_builder::TypedBuilder;
   diesel(belongs_to(crate::source::custom_emoji::CustomEmoji))
 )]
 #[cfg_attr(feature = "full", ts(export))]
+/// A custom keyword for an emoji.
 pub struct CustomEmojiKeyword {
   pub id: i32,
   pub custom_emoji_id: CustomEmojiId,

crates/db_schema/src/source/instance.rs

@@ -13,6 +13,7 @@ use typed_builder::TypedBuilder;
 #[cfg_attr(feature = "full", derive(Queryable, Identifiable, TS))]
 #[cfg_attr(feature = "full", diesel(table_name = instance))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A federated instance / site.
 pub struct Instance {
   pub id: InstanceId,
   pub domain: String,

crates/db_schema/src/source/language.rs

@@ -9,6 +9,7 @@ use ts_rs::TS;
 #[cfg_attr(feature = "full", derive(Queryable, Identifiable, TS))]
 #[cfg_attr(feature = "full", diesel(table_name = language))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A language.
 pub struct Language {
   pub id: LanguageId,
   pub code: String,

crates/db_schema/src/source/local_site.rs

@@ -17,31 +17,50 @@ use typed_builder::TypedBuilder;
 #[cfg_attr(feature = "full", diesel(table_name = local_site))]
 #[cfg_attr(feature = "full", diesel(belongs_to(crate::source::site::Site)))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The local site.
 pub struct LocalSite {
   pub id: LocalSiteId,
   pub site_id: SiteId,
+  /// True if the site is set up.
   pub site_setup: bool,
+  /// Whether downvotes are enabled.
   pub enable_downvotes: bool,
+  /// Whether NSFW is enabled.
   pub enable_nsfw: bool,
+  /// Whether only admins can create communities.
   pub community_creation_admin_only: bool,
+  /// Whether emails are required.
   pub require_email_verification: bool,
+  /// An optional registration application questionnaire in markdown.
   pub application_question: Option<String>,
+  /// Whether the instance is private or public.
   pub private_instance: bool,
+  /// The default front-end theme.
   pub default_theme: String,
   pub default_post_listing_type: ListingType,
+  /// An optional legal disclaimer page.
   pub legal_information: Option<String>,
+  /// Whether to hide mod names on the modlog.
   pub hide_modlog_mod_names: bool,
+  /// Whether new applications email admins.
   pub application_email_admins: bool,
+  /// An optional regex to filter words.
   pub slur_filter_regex: Option<String>,
+  /// The max actor name length.
   pub actor_name_max_length: i32,
+  /// Whether federation is enabled.
   pub federation_enabled: bool,
   pub federation_debug: bool,
+  /// The number of concurrent federation http workers.
   pub federation_worker_count: i32,
+  /// Whether captcha is enabled.
   pub captcha_enabled: bool,
+  /// The captcha difficulty.
   pub captcha_difficulty: String,
   pub published: chrono::NaiveDateTime,
   pub updated: Option<chrono::NaiveDateTime>,
   pub registration_mode: RegistrationMode,
+  /// Whether to email admins on new reports.
   pub reports_email_admins: bool,
 }
 

crates/db_schema/src/source/local_site_rate_limit.rs

@@ -16,6 +16,7 @@ use typed_builder::TypedBuilder;
   diesel(belongs_to(crate::source::local_site::LocalSite))
 )]
 #[cfg_attr(feature = "full", ts(export))]
+/// Rate limits for your site. Given in count / length of time.
 pub struct LocalSiteRateLimit {
   pub id: i32,
   pub local_site_id: LocalSiteId,

crates/db_schema/src/source/local_user.rs

@@ -16,28 +16,40 @@ use typed_builder::TypedBuilder;
 #[cfg_attr(feature = "full", derive(Queryable, Identifiable, TS))]
 #[cfg_attr(feature = "full", diesel(table_name = local_user))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A local user.
 pub struct LocalUser {
   pub id: LocalUserId,
+  /// The person_id for the local user.
   pub person_id: PersonId,
   #[serde(skip)]
   pub password_encrypted: String,
   pub email: Option<String>,
+  /// Whether to show NSFW content.
   pub show_nsfw: bool,
   pub theme: String,
   pub default_sort_type: SortType,
   pub default_listing_type: ListingType,
   pub interface_language: String,
+  /// Whether to show avatars.
   pub show_avatars: bool,
   pub send_notifications_to_email: bool,
+  /// A validation ID used in logging out sessions.
   pub validator_time: chrono::NaiveDateTime,
+  /// Whether to show comment / post scores.
   pub show_scores: bool,
+  /// Whether to show bot accounts.
   pub show_bot_accounts: bool,
+  /// Whether to show read posts.
   pub show_read_posts: bool,
+  /// Whether to show new posts as notifications.
   pub show_new_post_notifs: bool,
+  /// Whether their email has been verified.
   pub email_verified: bool,
+  /// Whether their registration application has been accepted.
   pub accepted_application: bool,
   #[serde(skip)]
   pub totp_2fa_secret: Option<String>,
+  /// A URL to add their 2-factor auth.
   pub totp_2fa_url: Option<String>,
 }
 

crates/db_schema/src/source/moderator.rs

@@ -27,6 +27,7 @@ use ts_rs::TS;
 #[cfg_attr(feature = "full", derive(Queryable, Identifiable, TS))]
 #[cfg_attr(feature = "full", diesel(table_name = mod_remove_post))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When a moderator removes a post.
 pub struct ModRemovePost {
   pub id: i32,
   pub mod_person_id: PersonId,
@@ -49,6 +50,7 @@ pub struct ModRemovePostForm {
 #[cfg_attr(feature = "full", derive(Queryable, Identifiable, TS))]
 #[cfg_attr(feature = "full", diesel(table_name = mod_lock_post))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When a moderator locks a post (prevents new comments being made).
 pub struct ModLockPost {
   pub id: i32,
   pub mod_person_id: PersonId,
@@ -69,6 +71,7 @@ pub struct ModLockPostForm {
 #[cfg_attr(feature = "full", derive(Queryable, Identifiable, TS))]
 #[cfg_attr(feature = "full", diesel(table_name = mod_feature_post))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When a moderator features a post on a community (pins it to the top).
 pub struct ModFeaturePost {
   pub id: i32,
   pub mod_person_id: PersonId,
@@ -92,6 +95,7 @@ pub struct ModFeaturePostForm {
 #[cfg_attr(feature = "full", derive(Queryable, Identifiable, TS))]
 #[cfg_attr(feature = "full", diesel(table_name = mod_remove_comment))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When a moderator removes a comment.
 pub struct ModRemoveComment {
   pub id: i32,
   pub mod_person_id: PersonId,
@@ -115,6 +119,7 @@ pub struct ModRemoveCommentForm {
 #[cfg_attr(feature = "full", derive(Queryable, Identifiable, TS))]
 #[cfg_attr(feature = "full", diesel(table_name = mod_remove_community))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When a moderator removes a community.
 pub struct ModRemoveCommunity {
   pub id: i32,
   pub mod_person_id: PersonId,
@@ -140,6 +145,7 @@ pub struct ModRemoveCommunityForm {
 #[cfg_attr(feature = "full", derive(Queryable, Identifiable, TS))]
 #[cfg_attr(feature = "full", diesel(table_name = mod_ban_from_community))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When someone is banned from a community.
 pub struct ModBanFromCommunity {
   pub id: i32,
   pub mod_person_id: PersonId,
@@ -167,6 +173,7 @@ pub struct ModBanFromCommunityForm {
 #[cfg_attr(feature = "full", derive(Queryable, Identifiable, TS))]
 #[cfg_attr(feature = "full", diesel(table_name = mod_ban))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When someone is banned from the site.
 pub struct ModBan {
   pub id: i32,
   pub mod_person_id: PersonId,
@@ -191,6 +198,7 @@ pub struct ModHideCommunityForm {
 #[cfg_attr(feature = "full", derive(Queryable, Identifiable, TS))]
 #[cfg_attr(feature = "full", diesel(table_name = mod_hide_community))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When a community is hidden from public view.
 pub struct ModHideCommunity {
   pub id: i32,
   pub community_id: CommunityId,
@@ -214,6 +222,7 @@ pub struct ModBanForm {
 #[cfg_attr(feature = "full", derive(Queryable, Identifiable, TS))]
 #[cfg_attr(feature = "full", diesel(table_name = mod_add_community))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When someone is added as a community moderator.
 pub struct ModAddCommunity {
   pub id: i32,
   pub mod_person_id: PersonId,
@@ -236,6 +245,7 @@ pub struct ModAddCommunityForm {
 #[cfg_attr(feature = "full", derive(Queryable, Identifiable, TS))]
 #[cfg_attr(feature = "full", diesel(table_name = mod_transfer_community))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When a moderator transfers a community to a new owner.
 pub struct ModTransferCommunity {
   pub id: i32,
   pub mod_person_id: PersonId,
@@ -256,6 +266,7 @@ pub struct ModTransferCommunityForm {
 #[cfg_attr(feature = "full", derive(Queryable, Identifiable, TS))]
 #[cfg_attr(feature = "full", diesel(table_name = mod_add))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When someone is added as a site moderator.
 pub struct ModAdd {
   pub id: i32,
   pub mod_person_id: PersonId,
@@ -277,6 +288,7 @@ pub struct ModAddForm {
 #[cfg_attr(feature = "full", derive(Queryable, Identifiable, TS))]
 #[cfg_attr(feature = "full", diesel(table_name = admin_purge_person))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When an admin purges a person.
 pub struct AdminPurgePerson {
   pub id: i32,
   pub admin_person_id: PersonId,
@@ -296,6 +308,7 @@ pub struct AdminPurgePersonForm {
 #[cfg_attr(feature = "full", derive(Queryable, Identifiable, TS))]
 #[cfg_attr(feature = "full", diesel(table_name = admin_purge_community))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When an admin purges a community.
 pub struct AdminPurgeCommunity {
   pub id: i32,
   pub admin_person_id: PersonId,
@@ -315,6 +328,7 @@ pub struct AdminPurgeCommunityForm {
 #[cfg_attr(feature = "full", derive(Queryable, Identifiable, TS))]
 #[cfg_attr(feature = "full", diesel(table_name = admin_purge_post))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When an admin purges a post.
 pub struct AdminPurgePost {
   pub id: i32,
   pub admin_person_id: PersonId,
@@ -336,6 +350,7 @@ pub struct AdminPurgePostForm {
 #[cfg_attr(feature = "full", derive(Queryable, Identifiable, TS))]
 #[cfg_attr(feature = "full", diesel(table_name = admin_purge_comment))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When an admin purges a comment.
 pub struct AdminPurgeComment {
   pub id: i32,
   pub admin_person_id: PersonId,

crates/db_schema/src/source/person.rs

@@ -12,16 +12,23 @@ use typed_builder::TypedBuilder;
 #[cfg_attr(feature = "full", derive(Queryable, Identifiable, TS))]
 #[cfg_attr(feature = "full", diesel(table_name = person))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A person.
 pub struct Person {
   pub id: PersonId,
   pub name: String,
+  /// A shorter display name.
   pub display_name: Option<String>,
+  /// A URL for an avatar.
   pub avatar: Option<DbUrl>,
+  /// Whether the person is banned.
   pub banned: bool,
   pub published: chrono::NaiveDateTime,
   pub updated: Option<chrono::NaiveDateTime>,
+  /// The federated actor_id.
   pub actor_id: DbUrl,
+  /// An optional bio, in markdown.
   pub bio: Option<String>,
+  /// Whether the person is local to our site.
   pub local: bool,
   #[serde(skip)]
   pub private_key: Option<String>,
@@ -29,15 +36,21 @@ pub struct Person {
   pub public_key: String,
   #[serde(skip)]
   pub last_refreshed_at: chrono::NaiveDateTime,
+  /// A URL for a banner.
   pub banner: Option<DbUrl>,
+  /// Whether the person is deleted.
   pub deleted: bool,
   #[serde(skip_serializing)]
   pub inbox_url: DbUrl,
   #[serde(skip)]
   pub shared_inbox_url: Option<DbUrl>,
+  /// A matrix id, usually given an @person:matrix.org
   pub matrix_user_id: Option<String>,
+  /// Whether the person is an admin.
   pub admin: bool,
+  /// Whether the person is a bot account.
   pub bot_account: bool,
+  /// When their ban, if it exists, expires, if at all.
   pub ban_expires: Option<chrono::NaiveDateTime>,
   pub instance_id: InstanceId,
 }

crates/db_schema/src/source/person_mention.rs

@@ -10,6 +10,7 @@ use ts_rs::TS;
 #[cfg_attr(feature = "full", diesel(belongs_to(crate::source::comment::Comment)))]
 #[cfg_attr(feature = "full", diesel(table_name = person_mention))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A person mention.
 pub struct PersonMention {
   pub id: PersonMentionId,
   pub recipient_id: PersonId,

crates/db_schema/src/source/post.rs

@@ -12,31 +12,46 @@ use typed_builder::TypedBuilder;
 #[cfg_attr(feature = "full", derive(Queryable, Identifiable, TS))]
 #[cfg_attr(feature = "full", diesel(table_name = post))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A post.
 pub struct Post {
   pub id: PostId,
   pub name: String,
   #[cfg_attr(feature = "full", ts(type = "string"))]
+  /// An optional link / url for the post.
   pub url: Option<DbUrl>,
+  /// An optional post body, in markdown.
   pub body: Option<String>,
   pub creator_id: PersonId,
   pub community_id: CommunityId,
+  /// Whether the post is removed.
   pub removed: bool,
+  /// Whether the post is locked.
   pub locked: bool,
   pub published: chrono::NaiveDateTime,
   pub updated: Option<chrono::NaiveDateTime>,
+  /// Whether the post is deleted.
   pub deleted: bool,
+  /// Whether the post is NSFW.
   pub nsfw: bool,
+  /// A title for the link.
   pub embed_title: Option<String>,
+  /// A description for the link.
   pub embed_description: Option<String>,
   #[cfg_attr(feature = "full", ts(type = "string"))]
+  /// A thumbnail picture url.
   pub thumbnail_url: Option<DbUrl>,
   #[cfg_attr(feature = "full", ts(type = "string"))]
+  /// The federated activity id / ap_id.
   pub ap_id: DbUrl,
+  /// Whether the post is local.
   pub local: bool,
   #[cfg_attr(feature = "full", ts(type = "string"))]
+  /// A video url for the link.
   pub embed_video_url: Option<DbUrl>,
   pub language_id: LanguageId,
+  /// Whether the post is featured to its community.
   pub featured_community: bool,
+  /// Whether the post is featured to its site.
   pub featured_local: bool,
 }
 

crates/db_schema/src/source/post_report.rs

@@ -12,12 +12,16 @@ use ts_rs::TS;
 #[cfg_attr(feature = "full", diesel(belongs_to(crate::source::post::Post)))] // Is this the right assoc?
 #[cfg_attr(feature = "full", diesel(table_name = post_report))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A post report.
 pub struct PostReport {
   pub id: PostReportId,
   pub creator_id: PersonId,
   pub post_id: PostId,
+  /// The original post title.
   pub original_post_name: String,
+  /// The original post url.
   pub original_post_url: Option<DbUrl>,
+  /// The original post body.
   pub original_post_body: Option<String>,
   pub reason: String,
   pub resolved: bool,

crates/db_schema/src/source/private_message.rs

@@ -16,6 +16,7 @@ use typed_builder::TypedBuilder;
 ))] // Is this the right assoc?
 #[cfg_attr(feature = "full", diesel(table_name = private_message))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A private message.
 pub struct PrivateMessage {
   pub id: PrivateMessageId,
   pub creator_id: PersonId,

crates/db_schema/src/source/private_message_report.rs

@@ -15,10 +15,12 @@ use ts_rs::TS;
 )]
 #[cfg_attr(feature = "full", diesel(table_name = private_message_report))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The private message report.
 pub struct PrivateMessageReport {
   pub id: PrivateMessageReportId,
   pub creator_id: PersonId,
   pub private_message_id: PrivateMessageId,
+  /// The original text.
   pub original_pm_text: String,
   pub reason: String,
   pub resolved: bool,

crates/db_schema/src/source/registration_application.rs

@@ -11,6 +11,7 @@ use ts_rs::TS;
 #[cfg_attr(feature = "full", derive(Queryable, Identifiable, TS))]
 #[cfg_attr(feature = "full", diesel(table_name = registration_application))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A registration application.
 pub struct RegistrationApplication {
   pub id: i32,
   pub local_user_id: LocalUserId,

crates/db_schema/src/source/site.rs

@@ -12,17 +12,25 @@ use typed_builder::TypedBuilder;
 #[cfg_attr(feature = "full", derive(Queryable, Identifiable, TS))]
 #[cfg_attr(feature = "full", diesel(table_name = site))]
 #[cfg_attr(feature = "full", ts(export))]
+/// The site.
 pub struct Site {
   pub id: SiteId,
   pub name: String,
+  /// A sidebar for the site in markdown.
   pub sidebar: Option<String>,
   pub published: chrono::NaiveDateTime,
   pub updated: Option<chrono::NaiveDateTime>,
+  /// An icon URL.
   pub icon: Option<DbUrl>,
+  /// A banner url.
   pub banner: Option<DbUrl>,
+  /// A shorter, one-line description of the site.
   pub description: Option<String>,
+  /// The federated actor_id.
   pub actor_id: DbUrl,
+  /// The time the site was last refreshed.
   pub last_refreshed_at: chrono::NaiveDateTime,
+  /// The site inbox
   pub inbox_url: DbUrl,
   pub private_key: Option<String>,
   pub public_key: String,

crates/db_schema/src/source/tagline.rs

@@ -15,6 +15,7 @@ use ts_rs::TS;
   diesel(belongs_to(crate::source::local_site::LocalSite))
 )]
 #[cfg_attr(feature = "full", ts(export))]
+/// A tagline, shown at the top of your site.
 pub struct Tagline {
   pub id: i32,
   pub local_site_id: LocalSiteId,

crates/db_views/src/structs.rs

@@ -28,6 +28,7 @@ use ts_rs::TS;
 #[derive(Debug, PartialEq, Eq, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A comment report view.
 pub struct CommentReportView {
   pub comment_report: CommentReport,
   pub comment: Comment,
@@ -36,8 +37,8 @@ pub struct CommentReportView {
   pub creator: Person,
   pub comment_creator: Person,
   pub counts: CommentAggregates,
-  pub creator_banned_from_community: bool, // Left Join to CommunityPersonBan
+  pub creator_banned_from_community: bool,
-  pub my_vote: Option<i16>,                // Left join to CommentLike
+  pub my_vote: Option<i16>,
   pub resolver: Option<Person>,
 }
 
@@ -45,22 +46,24 @@ pub struct CommentReportView {
 #[derive(Debug, PartialEq, Eq, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A comment view.
 pub struct CommentView {
   pub comment: Comment,
   pub creator: Person,
   pub post: Post,
   pub community: Community,
   pub counts: CommentAggregates,
-  pub creator_banned_from_community: bool, // Left Join to CommunityPersonBan
+  pub creator_banned_from_community: bool,
-  pub subscribed: SubscribedType,          // Left join to CommunityFollower
+  pub subscribed: SubscribedType,
-  pub saved: bool,                         // Left join to CommentSaved
+  pub saved: bool,
-  pub creator_blocked: bool,               // Left join to PersonBlock
+  pub creator_blocked: bool,
-  pub my_vote: Option<i16>,                // Left join to CommentLike
+  pub my_vote: Option<i16>,
 }
 
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A local user view.
 pub struct LocalUserView {
   pub local_user: LocalUser,
   pub person: Person,
@@ -71,6 +74,7 @@ pub struct LocalUserView {
 #[derive(Debug, PartialEq, Eq, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A post report view.
 pub struct PostReportView {
   pub post_report: PostReport,
   pub post: Post,
@@ -87,23 +91,25 @@ pub struct PostReportView {
 #[derive(Debug, PartialEq, Eq, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A post view.
 pub struct PostView {
   pub post: Post,
   pub creator: Person,
   pub community: Community,
-  pub creator_banned_from_community: bool, // Left Join to CommunityPersonBan
+  pub creator_banned_from_community: bool,
   pub counts: PostAggregates,
-  pub subscribed: SubscribedType, // Left join to CommunityFollower
+  pub subscribed: SubscribedType,
-  pub saved: bool,                // Left join to PostSaved
+  pub saved: bool,
-  pub read: bool,                 // Left join to PostRead
+  pub read: bool,
-  pub creator_blocked: bool,      // Left join to PersonBlock
+  pub creator_blocked: bool,
-  pub my_vote: Option<i16>,       // Left join to PostLike
+  pub my_vote: Option<i16>,
-  pub unread_comments: i64,       // Left join to PersonPostAggregates
+  pub unread_comments: i64,
 }
 
 #[derive(Debug, PartialEq, Eq, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A private message view.
 pub struct PrivateMessageView {
   pub private_message: PrivateMessage,
   pub creator: Person,
@@ -114,6 +120,7 @@ pub struct PrivateMessageView {
 #[derive(Debug, PartialEq, Eq, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A private message report view.
 pub struct PrivateMessageReportView {
   pub private_message_report: PrivateMessageReport,
   pub private_message: PrivateMessage,
@@ -126,6 +133,7 @@ pub struct PrivateMessageReportView {
 #[derive(Debug, PartialEq, Eq, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A registration application view.
 pub struct RegistrationApplicationView {
   pub registration_application: RegistrationApplication,
   pub creator_local_user: LocalUser,
@@ -136,6 +144,7 @@ pub struct RegistrationApplicationView {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A site view.
 pub struct SiteView {
   pub site: Site,
   pub local_site: LocalSite,
@@ -146,6 +155,7 @@ pub struct SiteView {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A custom emoji view.
 pub struct CustomEmojiView {
   pub custom_emoji: CustomEmoji,
   pub keywords: Vec<CustomEmojiKeyword>,

crates/db_views_actor/src/structs.rs

@@ -18,6 +18,7 @@ use ts_rs::TS;
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A community block.
 pub struct CommunityBlockView {
   pub person: Person,
   pub community: Community,
@@ -26,6 +27,7 @@ pub struct CommunityBlockView {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A community follower.
 pub struct CommunityFollowerView {
   pub community: Community,
   pub follower: Person,
@@ -34,12 +36,14 @@ pub struct CommunityFollowerView {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A community moderator.
 pub struct CommunityModeratorView {
   pub community: Community,
   pub moderator: Person,
 }
 
 #[derive(Debug, Serialize, Deserialize, Clone)]
+/// A community person ban.
 pub struct CommunityPersonBanView {
   pub community: Community,
   pub person: Person,
@@ -48,6 +52,7 @@ pub struct CommunityPersonBanView {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A community view.
 pub struct CommunityView {
   pub community: Community,
   pub subscribed: SubscribedType,
@@ -58,6 +63,7 @@ pub struct CommunityView {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A person block.
 pub struct PersonBlockView {
   pub person: Person,
   pub target: Person,
@@ -67,6 +73,7 @@ pub struct PersonBlockView {
 #[derive(Debug, PartialEq, Eq, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A person mention view.
 pub struct PersonMentionView {
   pub person_mention: PersonMention,
   pub comment: Comment,
@@ -75,17 +82,18 @@ pub struct PersonMentionView {
   pub community: Community,
   pub recipient: Person,
   pub counts: CommentAggregates,
-  pub creator_banned_from_community: bool, // Left Join to CommunityPersonBan
+  pub creator_banned_from_community: bool,
-  pub subscribed: SubscribedType,          // Left join to CommunityFollower
+  pub subscribed: SubscribedType,
-  pub saved: bool,                         // Left join to CommentSaved
+  pub saved: bool,
-  pub creator_blocked: bool,               // Left join to PersonBlock
+  pub creator_blocked: bool,
-  pub my_vote: Option<i16>,                // Left join to CommentLike
+  pub my_vote: Option<i16>,
 }
 
 #[skip_serializing_none]
 #[derive(Debug, PartialEq, Eq, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A comment reply view.
 pub struct CommentReplyView {
   pub comment_reply: CommentReply,
   pub comment: Comment,
@@ -104,6 +112,7 @@ pub struct CommentReplyView {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// A person view.
 pub struct PersonView {
   pub person: Person,
   pub counts: PersonAggregates,

crates/db_views_moderator/src/structs.rs

@@ -33,6 +33,7 @@ use ts_rs::TS;
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When someone is added as a community moderator.
 pub struct ModAddCommunityView {
   pub mod_add_community: ModAddCommunity,
   pub moderator: Option<Person>,
@@ -44,6 +45,7 @@ pub struct ModAddCommunityView {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When someone is added as a site moderator.
 pub struct ModAddView {
   pub mod_add: ModAdd,
   pub moderator: Option<Person>,
@@ -54,6 +56,7 @@ pub struct ModAddView {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When someone is banned from a community.
 pub struct ModBanFromCommunityView {
   pub mod_ban_from_community: ModBanFromCommunity,
   pub moderator: Option<Person>,
@@ -65,6 +68,7 @@ pub struct ModBanFromCommunityView {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When someone is banned from the site.
 pub struct ModBanView {
   pub mod_ban: ModBan,
   pub moderator: Option<Person>,
@@ -75,6 +79,7 @@ pub struct ModBanView {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When a community is hidden from public view.
 pub struct ModHideCommunityView {
   pub mod_hide_community: ModHideCommunity,
   pub admin: Option<Person>,
@@ -85,6 +90,7 @@ pub struct ModHideCommunityView {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When a moderator locks a post (prevents new comments being made).
 pub struct ModLockPostView {
   pub mod_lock_post: ModLockPost,
   pub moderator: Option<Person>,
@@ -96,6 +102,7 @@ pub struct ModLockPostView {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When a moderator removes a comment.
 pub struct ModRemoveCommentView {
   pub mod_remove_comment: ModRemoveComment,
   pub moderator: Option<Person>,
@@ -109,6 +116,7 @@ pub struct ModRemoveCommentView {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When a moderator removes a community.
 pub struct ModRemoveCommunityView {
   pub mod_remove_community: ModRemoveCommunity,
   pub moderator: Option<Person>,
@@ -119,6 +127,7 @@ pub struct ModRemoveCommunityView {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When a moderator removes a post.
 pub struct ModRemovePostView {
   pub mod_remove_post: ModRemovePost,
   pub moderator: Option<Person>,
@@ -130,6 +139,7 @@ pub struct ModRemovePostView {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When a moderator features a post on a community (pins it to the top).
 pub struct ModFeaturePostView {
   pub mod_feature_post: ModFeaturePost,
   pub moderator: Option<Person>,
@@ -141,6 +151,7 @@ pub struct ModFeaturePostView {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When a moderator transfers a community to a new owner.
 pub struct ModTransferCommunityView {
   pub mod_transfer_community: ModTransferCommunity,
   pub moderator: Option<Person>,
@@ -152,6 +163,7 @@ pub struct ModTransferCommunityView {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When an admin purges a comment.
 pub struct AdminPurgeCommentView {
   pub admin_purge_comment: AdminPurgeComment,
   pub admin: Option<Person>,
@@ -162,6 +174,7 @@ pub struct AdminPurgeCommentView {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When an admin purges a community.
 pub struct AdminPurgeCommunityView {
   pub admin_purge_community: AdminPurgeCommunity,
   pub admin: Option<Person>,
@@ -171,6 +184,7 @@ pub struct AdminPurgeCommunityView {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When an admin purges a person.
 pub struct AdminPurgePersonView {
   pub admin_purge_person: AdminPurgePerson,
   pub admin: Option<Person>,
@@ -180,6 +194,7 @@ pub struct AdminPurgePersonView {
 #[derive(Debug, Serialize, Deserialize, Clone)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// When an admin purges a post.
 pub struct AdminPurgePostView {
   pub admin_purge_post: AdminPurgePost,
   pub admin: Option<Person>,
@@ -190,6 +205,7 @@ pub struct AdminPurgePostView {
 #[derive(Debug, Serialize, Deserialize, Clone, Copy)]
 #[cfg_attr(feature = "full", derive(TS))]
 #[cfg_attr(feature = "full", ts(export))]
+/// Querying / filtering the modlog.
 pub struct ModlogListParams {
   pub community_id: Option<CommunityId>,
   pub mod_person_id: Option<PersonId>,