Adding some API comments.

src/interfaces/api/comment.ts

@@ -4,7 +4,7 @@ export interface CreateComment {
   content: string;
   parent_id?: number;
   post_id: number;
-  form_id?: string;
+  form_id?: string; // An optional front end ID, to tell which is coming back
   auth: string;
 }
 
@@ -15,12 +15,18 @@ export interface EditComment {
   auth: string;
 }
 
+/**
+ * Only the creator can delete the comment.
+ */
 export interface DeleteComment {
   edit_id: number;
   deleted: boolean;
   auth: string;
 }
 
+/**
+ * Only a mod or admin can remove the comment.
+ */
 export interface RemoveComment {
   edit_id: number;
   removed: boolean;
@@ -28,6 +34,9 @@ export interface RemoveComment {
   auth: string;
 }
 
+/**
+ * Only the recipient can do this.
+ */
 export interface MarkCommentAsRead {
   comment_id: number;
   read: boolean;
@@ -42,8 +51,8 @@ export interface SaveComment {
 
 export interface CommentResponse {
   comment_view: CommentView;
-  recipient_ids: number[]; // TODO another way to do this? Maybe a UserMention belongs to Comment
+  recipient_ids: number[];
-  form_id?: string; // An optional front end ID, to tell which is coming ba,
+  form_id?: string; // An optional front end ID, to tell which is coming back
 }
 
 export interface CreateCommentLike {
@@ -52,6 +61,11 @@ export interface CreateCommentLike {
   auth: string;
 }
 
+/**
+ * Comment listing types are `All, Subscribed, Community`
+ *
+ * `community_name` can only be used for local communities. To get posts for a federated community, pass `community_id` instead.
+ */
 export interface GetComments {
   type_: string;
   sort: string;

src/interfaces/api/community.ts

@@ -47,7 +47,7 @@ export interface BanFromCommunity {
   community_id: number;
   user_id: number;
   ban: boolean;
-  remove_data: boolean;
+  remove_data: boolean; // Removes/Restores their comments and posts for that community
   reason?: string;
   expires?: number;
   auth: string;
@@ -69,6 +69,9 @@ export interface AddModToCommunityResponse {
   moderators: CommunityModeratorView[];
 }
 
+/**
+ * Only mods can edit a community.
+ */
 export interface EditCommunity {
   edit_id: number;
   title: string;
@@ -86,6 +89,9 @@ export interface DeleteCommunity {
   auth: string;
 }
 
+/**
+ * Only admins can remove a community.
+ */
 export interface RemoveCommunity {
   edit_id: number;
   removed: boolean;
@@ -114,6 +120,9 @@ export interface TransferCommunity {
   auth: string;
 }
 
+/**
+ * The main / frontpage community is `community_id: 0`.
+ */
 export interface CommunityJoin {
   community_id: number;
 }

src/interfaces/api/post.ts

@@ -32,6 +32,11 @@ export interface GetPostResponse {
   online: number;
 }
 
+/**
+ * Post listing types are `All, Subscribed, Community`
+ *
+ * `community_name` can only be used for local communities. To get posts for a federated community, pass `community_id` instead.
+ */
 export interface GetPosts {
   type_: string;
   sort: string;
@@ -46,6 +51,9 @@ export interface GetPostsResponse {
   posts: PostView[];
 }
 
+/**
+ * `score` can be 0, -1, or 1
+ */
 export interface CreatePostLike {
   post_id: number;
   score: number;
@@ -67,6 +75,9 @@ export interface DeletePost {
   auth: string;
 }
 
+/**
+ * Only admins and mods can remove a post.
+ */
 export interface RemovePost {
   edit_id: number;
   removed: boolean;
@@ -74,12 +85,18 @@ export interface RemovePost {
   auth: string;
 }
 
+/**
+ * Only admins and mods can lock a post.
+ */
 export interface LockPost {
   edit_id: number;
   locked: boolean;
   auth: string;
 }
 
+/**
+ * Only admins and mods can sticky a post.
+ */
 export interface StickyPost {
   edit_id: number;
   stickied: boolean;

src/interfaces/api/site.ts

@@ -22,6 +22,9 @@ export interface ListCategoriesResponse {
   categories: Category[];
 }
 
+/**
+ * Search types are `All, Comments, Posts, Communities, Users, Url`
+ */
 export interface Search {
   q: string;
   type_: string;
@@ -96,7 +99,7 @@ export interface GetSiteResponse {
   banned: UserViewSafe[];
   online: number;
   version: string;
-  my_user?: User_;
+  my_user?: User_; // Gives back your user and settings if logged in
   federated_instances: string[];
 }
 

src/interfaces/api/user.ts

@@ -14,6 +14,9 @@ export interface Login {
   password: string;
 }
 
+/**
+ * Only the first user will be able to be the admin.
+ */
 export interface Register {
   username: string;
   email?: string;
@@ -21,14 +24,14 @@ export interface Register {
   password_verify: string;
   admin: boolean;
   show_nsfw: boolean;
-  captcha_uuid?: string;
+  captcha_uuid?: string; // Only checked if these are enabled in the server
   captcha_answer?: string;
 }
 
 export interface GetCaptcha {}
 
 export interface GetCaptchaResponse {
-  ok?: CaptchaResponse;
+  ok?: CaptchaResponse; // Will be undefined if captchas are disabled
 }
 
 export interface CaptchaResponse {
@@ -39,9 +42,9 @@ export interface CaptchaResponse {
 
 export interface SaveUserSettings {
   show_nsfw: boolean;
-  theme: string;
+  theme: string; // Default 'default'
-  default_sort_type: number;
+  default_sort_type: number; // The Sort types from above, zero indexed as a number
-  default_listing_type: number;
+  default_listing_type: number; // Post listing types are `All, Subscribed, Community`
   lang: string;
   avatar?: string;
   banner?: string;
@@ -57,10 +60,16 @@ export interface SaveUserSettings {
   auth: string;
 }
 
+/**
+ * The `jwt` string should be stored and used anywhere `auth` is called for.
+ */
 export interface LoginResponse {
   jwt: string;
 }
 
+/**
+ * `username` can only be used for local users. To get details for a federated user, pass `user_id` instead.
+ */
 export interface GetUserDetails {
   user_id?: number;
   username?: string;
@@ -106,7 +115,7 @@ export interface AddAdminResponse {
 export interface BanUser {
   user_id: number;
   ban: boolean;
-  remove_data: boolean;
+  remove_data: boolean; // Removes/Restores their comments, posts, and communities
   reason?: string;
   expires?: number;
   auth: string;
@@ -143,6 +152,9 @@ export interface UserMentionResponse {
   user_mention_view: UserMentionView;
 }
 
+/**
+ * Permanently deletes your posts and comments
+ */
 export interface DeleteAccount {
   password: string;
   auth: string;
@@ -207,6 +219,9 @@ export interface UserJoinResponse {
   joined: boolean;
 }
 
+/**
+ * If a community is supplied, returns the report count for only that community, otherwise returns the report count for all communities the user moderates.
+ */
 export interface GetReportCount {
   community?: number;
   auth: string;

src/interfaces/views.ts

@@ -46,10 +46,10 @@ export interface UserMentionView {
   community: CommunitySafe;
   recipient: UserSafe;
   counts: CommentAggregates;
-  creator_banned_from_community: boolean; // Left Join to CommunityUserBan
+  creator_banned_from_community: boolean;
-  subscribed: boolean; // Left join to CommunityFollower
+  subscribed: boolean;
-  saved: boolean; // Left join to CommentSaved
+  saved: boolean;
-  my_vote?: number; // Left join to CommentLi,
+  my_vote?: number;
 }
 
 export interface SiteView {
@@ -68,12 +68,12 @@ export interface PostView {
   post: Post;
   creator: UserSafe;
   community: CommunitySafe;
-  creator_banned_from_community: boolean; // Left Join to CommunityUserBan
+  creator_banned_from_community: boolean;
   counts: PostAggregates;
-  subscribed: boolean; // Left join to CommunityFollower
+  subscribed: boolean;
-  saved: boolean; // Left join to PostSaved
+  saved: boolean;
-  read: boolean; // Left join to PostRead
+  read: boolean;
-  my_vote?: number; // Left join to PostLi,
+  my_vote?: number;
 }
 
 export interface PostReportView {
@@ -88,14 +88,14 @@ export interface PostReportView {
 export interface CommentView {
   comment: Comment;
   creator: UserSafe;
-  recipient?: UserSafe; // Left joins to comment and us,
+  recipient?: UserSafe;
   post: Post;
   community: CommunitySafe;
   counts: CommentAggregates;
-  creator_banned_from_community: boolean; // Left Join to CommunityUserBan
+  creator_banned_from_community: boolean;
-  subscribed: boolean; // Left join to CommunityFollower
+  subscribed: boolean;
-  saved: boolean; // Left join to CommentSaved
+  saved: boolean;
-  my_vote?: number; // Left join to CommentLi,
+  my_vote?: number;
 }
 
 export interface CommentReportView {