Docs

src/api/channels/channels.rs

@@ -28,6 +28,9 @@ impl Channel {
 
     /// Deletes self.
     ///
+    /// Requires the [`MANAGE_CHANNEL`](crate::types::PermissionFlags::MANAGE_CHANNEL) permission in a guild, or
+    /// the [`MANAGE_THREADS`](crate::types::PermissionFlags::MANAGE_THREADS) permission if the channel is a thread.
+    ///
     /// # Reference
     /// See <https://discord-userdoccers.vercel.app/resources/channel#delete-channel>
     pub async fn delete(self, user: &mut UserMeta) -> ChorusResult<()> {
@@ -47,6 +50,15 @@ impl Channel {
     /// Modifies a channel with the provided data.
     /// Returns the new Channel.
     ///
+    /// Requires the [`MANAGE_CHANNEL`](crate::types::PermissionFlags::MANAGE_CHANNEL) permission in a guild.
+    ///
+    /// If modifying permission overwrites, the [`MANAGE_ROLES`](crate::types::PermissionFlags::MANAGE_ROLES) permission is required.
+    /// Only permissions you have in the guild or parent channel (if applicable) can be allowed/denied
+    /// (unless you have a [`MANAGE_ROLES`](crate::types::PermissionFlags::MANAGE_ROLES) overwrite in the channel).
+    ///
+    /// If modifying a thread and setting `archived` to `false`, when `locked` is also `false`, only the [`SEND_MESSAGES`](crate::types::PermissionFlags::SEND_MESSAGES) permission is required.
+    /// Otherwise, requires the [`MANAGE_THREADS`](crate::types::PermissionFlags::MANAGE_THREADS) permission. Requires the thread to have `archived` set to `false` or be set to `false` in the request.
+    ///
     /// # Reference
     /// See <https://discord-userdoccers.vercel.app/resources/channel#modify-channel>
     pub async fn modify(
@@ -71,6 +83,11 @@ impl Channel {
 
     /// Fetches recent messages from a channel.
     ///
+    /// If operating on a guild channel, this endpoint requires the [`VIEW_CHANNEL`](crate::types::PermissionFlags::VIEW_CHANNEL) permission.
+    ///
+    /// If the user is missing the [`READ_MESSAGE_HISTORY`](crate::types::PermissionFlags::READ_MESSAGE_HISTORY) permission,
+    /// this method returns an empty list.
+    ///
     /// # Reference
     /// See <https://discord-userdoccers.vercel.app/resources/message#get-messages>
     pub async fn messages(

src/api/channels/permissions.rs

@@ -10,7 +10,13 @@ use crate::{
 };
 
 impl types::Channel {
-    /// Edits the permission overwrites for a channel.
+    /// Edits the permission overwrites for a user or role in a channel.
+    ///
+    /// Only usable for guild channels.
+    ///
+    /// Requires the [`MANAGE_ROLES`](crate::types::PermissionFlags::MANAGE_ROLES) permission.
+    /// Only permissions you have in the guild or parent channel (if applicable) can be allowed/denied
+    /// (unless you have a [`MANAGE_ROLES`](crate::types::PermissionFlags::MANAGE_ROLES) overwrite in the channel).
     ///
     /// # Reference
     /// See <https://discord-userdoccers.vercel.app/resources/channel#modify-channel-permissions>
@@ -40,7 +46,11 @@ impl types::Channel {
         chorus_request.handle_request_as_result(user).await
     }
 
-    /// Deletes a permission overwrite for a channel.
+    /// Deletes a permission overwrite for a user or role in a channel.
+    ///
+    /// Only usable for guild channels.
+    ///
+    /// Requires the [`MANAGE_ROLES`](crate::types::PermissionFlags::MANAGE_ROLES) permission.
     ///
     /// # Reference
     /// See <https://discord-userdoccers.vercel.app/resources/channel#delete-channel-permission>

src/api/channels/reactions.rs

@@ -17,9 +17,7 @@ pub struct ReactionMeta {
 impl ReactionMeta {
     /// Deletes all reactions for a message.
     ///
-    /// This endpoint requires the `MANAGE_MESSAGES` permission to be present on the current user.
-    ///
-    /// Fires a `Message Reaction Remove All` Gateway event.
+    /// This endpoint requires the [`MANAGE_MESSAGES`](crate::types::PermissionFlags::MANAGE_MESSAGES) permission.
     ///
     /// # Reference
     /// See <https://discord.com/developers/docs/resources/channel#delete-all-reactions>
@@ -63,13 +61,11 @@ impl ReactionMeta {
 
     /// Deletes all the reactions for a given emoji on a message.
     ///
-    /// This endpoint requires the `MANAGE_MESSAGES` permission.
+    /// This endpoint requires the [`MANAGE_MESSAGES`](crate::types::PermissionFlags::MANAGE_MESSAGES) permission.
     ///
     /// The emoji must be URL Encoded or the request will fail with 10014: Unknown Emoji.
     /// To use custom emoji, the format of the emoji string must be name:id.
     ///
-    /// Fires the `Message Reaction Remove Emoji` Gateway event.
-    ///
     /// # Reference
     /// See <https://discord.com/developers/docs/resources/channel#delete-all-reactions-for-emoji>
     pub async fn delete_emoji(&self, emoji: &str, user: &mut UserMeta) -> ChorusResult<()> {
@@ -89,10 +85,10 @@ impl ReactionMeta {
 
     /// Create a reaction on a message.
     ///
-    /// This endpoint requires the `READ_MESSAGE_HISTORY` permission.
+    /// This endpoint requires the [`READ_MESSAGE_HISTORY`](crate::types::PermissionFlags::READ_MESSAGE_HISTORY) permission.
     ///
     /// Additionally, if nobody else has reacted to the message using this emoji,
-    /// this endpoint requires the `ADD_REACTIONS` permission.
+    /// this endpoint requires the [`ADD_REACTIONS`](crate::types::PermissionFlags::ADD_REACTIONS) permission.
     ///
     /// The emoji must be URL Encoded or the request will fail with 10014: Unknown Emoji.
     /// To use custom emoji, the format of the emoji string must be `name:id`.
@@ -119,8 +115,6 @@ impl ReactionMeta {
     /// The reaction emoji must be URL Encoded or the request will fail with 10014: Unknown Emoji.
     /// To use custom emoji, the format of the emoji string must be name:id.
     ///
-    /// Fires a `Message Reaction Remove` Gateway event.
-    ///
     /// # Reference
     /// See <https://discord.com/developers/docs/resources/channel#delete-own-reaction>
     pub async fn remove(&self, emoji: &str, user: &mut UserMeta) -> ChorusResult<()> {
@@ -140,13 +134,11 @@ impl ReactionMeta {
 
     /// Deletes a user's reaction to a message.
     ///
-    /// This endpoint requires the `MANAGE_MESSAGES` permission.
+    /// This endpoint requires the [`MANAGE_MESSAGES`](crate::types::PermissionFlags::MANAGE_MESSAGES) permission.
     ///
     /// The reaction emoji must be URL Encoded or the request will fail with 10014: Unknown Emoji.
     /// To use custom emoji, the format of the emoji string must be name:id.
     ///
-    /// Fires a `Message Reaction Remove` Gateway event.
-    ///
     /// # Reference
     /// See <https://discord.com/developers/docs/resources/channel#delete-user-reaction>
     pub async fn delete_user(

src/api/guilds/guilds.rs

@@ -32,6 +32,8 @@ impl Guild {
 
     /// Deletes a guild by its id.
     ///
+    /// User must be the owner.
+    ///
     /// # Example
     ///
     /// ```rs
@@ -118,7 +120,7 @@ impl Guild {
     /// Fetches a guild by its id.
     ///
     /// # Reference
-    /// See <https://discord-userdoccers.vercel.app/resources/channel#get-channel>
+    /// See <https://discord-userdoccers.vercel.app/resources/guild#get-guild>
     pub async fn get(guild_id: Snowflake, user: &mut UserMeta) -> ChorusResult<Guild> {
         let chorus_request = ChorusRequest {
             request: Client::new()

src/api/guilds/member.rs

@@ -35,6 +35,8 @@ impl types::GuildMember {
 
     /// Adds a role to a guild member.
     ///
+    /// Requires the [`MANAGE_ROLES`](crate::types::PermissionFlags::MANAGE_ROLES) permission.
+    ///
     /// # Reference
     /// See <https://discord-userdoccers.vercel.app/resources/guild#add-guild-member-role>
     pub async fn add_role(
@@ -59,6 +61,8 @@ impl types::GuildMember {
 
     /// Removes a role from a guild member.
     ///
+    /// Requires the [`MANAGE_ROLES`](crate::types::PermissionFlags::MANAGE_ROLES) permission.
+    ///
     /// # Reference
     /// See <https://discord-userdoccers.vercel.app/resources/guild#remove-guild-member-role>
     pub async fn remove_role(

src/api/guilds/roles.rs

@@ -58,6 +58,8 @@ impl types::RoleObject {
 
     /// Creates a new role for a given guild.
     ///
+    /// Requires the [`MANAGE_ROLES`](crate::types::PermissionFlags::MANAGE_ROLES) permission.
+    ///
     /// # Reference
     /// See <https://discord-userdoccers.vercel.app/resources/guild#create-guild-role>
     pub async fn create(
@@ -86,6 +88,8 @@ impl types::RoleObject {
 
     /// Updates the position of a role in a given guild's hierarchy.
     ///
+    /// Requires the [`MANAGE_ROLES`](crate::types::PermissionFlags::MANAGE_ROLES) permission.
+    ///
     /// # Reference
     /// See <https://discord-userdoccers.vercel.app/resources/guild#modify-guild-role-positions>
     pub async fn position_update(
@@ -116,6 +120,8 @@ impl types::RoleObject {
 
     /// Updates a role in a guild.
     ///
+    /// Requires the [`MANAGE_ROLES`](crate::types::PermissionFlags::MANAGE_ROLES) permission.
+    ///
     /// # Reference
     /// See <https://discord-userdoccers.vercel.app/resources/guild#modify-guild-role>
     pub async fn update(

src/api/invites/mod.rs

@@ -11,10 +11,8 @@ impl UserMeta {
     ///
     /// Note that the session ID is required for guest invites.
     ///
-    /// May fire a Guild Create, Channel Create, and/or Relationship Add Gateway event.
-    ///
     /// # Reference:
-    /// Read <https://discord-userdoccers.vercel.app/resources/invite#accept-invite>
+    /// See <https://discord-userdoccers.vercel.app/resources/invite#accept-invite>
     pub async fn accept_invite(
         &mut self,
         invite_code: &str,
@@ -43,7 +41,7 @@ impl UserMeta {
     /// Note: Spacebar does not yet implement this endpoint.
     ///
     /// # Reference:
-    /// Read <https://discord-userdoccers.vercel.app/resources/invite#create-user-invite>
+    /// See <https://discord-userdoccers.vercel.app/resources/invite#create-user-invite>
     pub async fn create_user_invite(&mut self, code: Option<&str>) -> ChorusResult<Invite> {
         ChorusRequest {
             request: Client::new()
@@ -62,10 +60,10 @@ impl UserMeta {
     /// Creates a new invite for a guild channel or group DM.
     ///
     /// # Guild Channels
-    /// For guild channels, the endpoint
-    /// requires the CREATE_INSTANT_INVITE permission.
+    /// For guild channels, the endpoint requires the [`CREATE_INSTANT_INVITE`](crate::types::PermissionFlags::CRATE_INSTANT_INVITE) permission.
     ///
-    /// Guild channel invites also fire an Invite Create Gateway event.
+    /// # Reference
+    /// See <https://discord-userdoccers.vercel.app/resources/invite#create-channel-invite>
     pub async fn create_channel_invite(
         &mut self,
         create_channel_invite_schema: CreateChannelInviteSchema,

src/api/policies/instance/instance.rs

@@ -6,6 +6,12 @@ use crate::types::GeneralConfiguration;
 
 impl Instance {
     /// Gets the instance policies schema.
+    ///
+    /// # Notes
+    /// This is a Spacebar only endpoint.
+    ///
+    /// # Reference
+    /// See <https://docs.spacebar.chat/routes/#get-/policies/instance/>
     pub async fn general_configuration_schema(&self) -> ChorusResult<GeneralConfiguration> {
         let endpoint_url = self.urls.api.clone() + "/policies/instance/";
         let request = match self.client.get(&endpoint_url).send().await {

src/api/users/channels.rs

@@ -12,8 +12,11 @@ use crate::{
 impl UserMeta {
     /// Creates a DM channel or group DM channel.
     ///
+    /// One recipient creates or returns an existing DM channel,
+    /// none or multiple recipients create a group DM channel.
+    ///
     /// # Reference:
-    /// Read <https://discord-userdoccers.vercel.app/resources/channel#create-private-channel>
+    /// See <https://discord-userdoccers.vercel.app/resources/channel#create-private-channel>
     pub async fn create_private_channel(
         &mut self,
         create_private_channel_schema: PrivateChannelCreateSchema,

src/api/users/guilds.rs

@@ -10,8 +10,10 @@ impl UserMeta {
     /// Leaves a given guild.
     ///
     /// # Reference:
-    /// Read <https://discord-userdoccers.vercel.app/resources/guild#leave-guild>
-    // TODO: Docs: What is lurking here?
+    /// See <https://discord-userdoccers.vercel.app/resources/guild#leave-guild>
+    // TODO: Docs: What is "lurking" here?
+    // It is documented as "Whether the user is lurking in the guild",
+    // but that says nothing about what this field actually does / means
     pub async fn leave_guild(&mut self, guild_id: &Snowflake, lurking: bool) -> ChorusResult<()> {
         ChorusRequest {
             request: Client::new()

src/ratelimiter.rs

@@ -292,6 +292,13 @@ impl ChorusRequest {
         }
     }
 
+    /// Gets the ratelimit configuration.
+    ///
+    /// # Notes
+    /// This is a spacebar only endpoint.
+    ///
+    /// # Reference
+    /// See <https://docs.spacebar.chat/routes/#get-/policies/instance/limits/>
     pub(crate) async fn get_limits_config(url_api: &str) -> ChorusResult<LimitsConfiguration> {
         let request = Client::new()
             .get(format!("{}/policies/instance/limits/", url_api))

src/types/entities/emoji.rs

@@ -5,6 +5,8 @@ use crate::types::Snowflake;
 
 #[derive(Debug, PartialEq, Eq, Clone, Deserialize, Serialize, Default)]
 #[cfg_attr(feature = "sqlx", derive(sqlx::FromRow))]
+/// # Reference
+/// See <https://discord-userdoccers.vercel.app/resources/emoji#emoji-object>
 pub struct Emoji {
     pub id: Option<Snowflake>,
     pub name: Option<String>,

src/types/entities/guild_member.rs

@@ -3,6 +3,10 @@ use serde::{Deserialize, Serialize};
 use crate::types::{entities::PublicUser, Snowflake};
 
 #[derive(Debug, Deserialize, Default, Serialize, Clone, PartialEq, Eq)]
+/// Represents a participating user in a guild.
+///
+/// # Reference
+/// See <https://discord-userdoccers.vercel.app/resources/guild#guild-member-object>
 pub struct GuildMember {
     pub user: Option<PublicUser>,
     pub nick: Option<String>,

src/types/entities/message.rs

@@ -1,5 +1,3 @@
-
-
 use serde::{Deserialize, Serialize};
 
 use crate::types::{
@@ -12,6 +10,10 @@ use crate::types::{
 
 #[derive(Debug, Serialize, Deserialize, Default, Clone, PartialEq)]
 #[cfg_attr(feature = "sqlx", derive(sqlx::FromRow))]
+/// Represents a message sent in a channel.
+///
+/// # Reference
+/// See <https://discord-userdoccers.vercel.app/resources/message#message-object>
 pub struct Message {
     pub id: Snowflake,
     pub channel_id: Snowflake,
@@ -66,6 +68,8 @@ pub struct Message {
 }
 
 #[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
+/// # Reference
+/// See <https://discord-userdoccers.vercel.app/resources/message#message-reference-object>
 pub struct MessageReference {
     pub message_id: Snowflake,
     pub channel_id: Snowflake,
@@ -201,6 +205,8 @@ pub enum Component {
 }
 
 #[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
+/// # Reference
+/// See <https://discord-userdoccers.vercel.app/resources/message#message-activity-object>
 pub struct MessageActivity {
     #[serde(rename = "type")]
     pub activity_type: i64,

src/types/entities/sticker.rs

@@ -4,6 +4,10 @@ use crate::types::{entities::User, utils::Snowflake};
 
 #[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
 #[cfg_attr(feature = "sqlx", derive(sqlx::FromRow))]
+/// Represents a sticker that can be sent in messages.
+///
+/// # Reference
+/// See <https://discord-userdoccers.vercel.app/resources/sticker#sticker-object>
 pub struct Sticker {
     #[serde(default)]
     pub id: Snowflake,
@@ -23,6 +27,12 @@ pub struct Sticker {
 }
 
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+/// A partial sticker object.
+///
+/// Represents the smallest amount of data required to render a sticker.
+///
+/// # Reference
+/// See <https://discord-userdoccers.vercel.app/resources/sticker#sticker-item-object>
 pub struct StickerItem {
     pub id: Snowflake,
     pub name: String,