diff --git a/src/api/channels/channels.rs b/src/api/channels/channels.rs index 0f6d64a..ba99a8f 100644 --- a/src/api/channels/channels.rs +++ b/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 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 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 pub async fn messages( diff --git a/src/api/channels/permissions.rs b/src/api/channels/permissions.rs index d68034e..7c83d85 100644 --- a/src/api/channels/permissions.rs +++ b/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 @@ -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 diff --git a/src/api/channels/reactions.rs b/src/api/channels/reactions.rs index cdf65ce..b7b221f 100644 --- a/src/api/channels/reactions.rs +++ b/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 @@ -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 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 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 pub async fn delete_user( diff --git a/src/api/guilds/guilds.rs b/src/api/guilds/guilds.rs index f598414..43a8cdf 100644 --- a/src/api/guilds/guilds.rs +++ b/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 + /// See pub async fn get(guild_id: Snowflake, user: &mut UserMeta) -> ChorusResult { let chorus_request = ChorusRequest { request: Client::new() diff --git a/src/api/guilds/member.rs b/src/api/guilds/member.rs index 06b5154..d3e0e80 100644 --- a/src/api/guilds/member.rs +++ b/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 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 pub async fn remove_role( diff --git a/src/api/guilds/roles.rs b/src/api/guilds/roles.rs index e76749e..1134332 100644 --- a/src/api/guilds/roles.rs +++ b/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 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 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 pub async fn update( diff --git a/src/api/invites/mod.rs b/src/api/invites/mod.rs index 343f44d..948a785 100644 --- a/src/api/invites/mod.rs +++ b/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 + /// See 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 + /// See pub async fn create_user_invite(&mut self, code: Option<&str>) -> ChorusResult { 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 pub async fn create_channel_invite( &mut self, create_channel_invite_schema: CreateChannelInviteSchema, diff --git a/src/api/policies/instance/instance.rs b/src/api/policies/instance/instance.rs index ae6e5d5..768c7fd 100644 --- a/src/api/policies/instance/instance.rs +++ b/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 pub async fn general_configuration_schema(&self) -> ChorusResult { let endpoint_url = self.urls.api.clone() + "/policies/instance/"; let request = match self.client.get(&endpoint_url).send().await { diff --git a/src/api/users/channels.rs b/src/api/users/channels.rs index 806bd9f..faa58ad 100644 --- a/src/api/users/channels.rs +++ b/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 + /// See pub async fn create_private_channel( &mut self, create_private_channel_schema: PrivateChannelCreateSchema, diff --git a/src/api/users/guilds.rs b/src/api/users/guilds.rs index dd52507..a446029 100644 --- a/src/api/users/guilds.rs +++ b/src/api/users/guilds.rs @@ -10,8 +10,10 @@ impl UserMeta { /// Leaves a given guild. /// /// # Reference: - /// Read - // TODO: Docs: What is lurking here? + /// See + // 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() diff --git a/src/ratelimiter.rs b/src/ratelimiter.rs index 9227737..0389ad3 100644 --- a/src/ratelimiter.rs +++ b/src/ratelimiter.rs @@ -292,6 +292,13 @@ impl ChorusRequest { } } + /// Gets the ratelimit configuration. + /// + /// # Notes + /// This is a spacebar only endpoint. + /// + /// # Reference + /// See pub(crate) async fn get_limits_config(url_api: &str) -> ChorusResult { let request = Client::new() .get(format!("{}/policies/instance/limits/", url_api)) diff --git a/src/types/entities/emoji.rs b/src/types/entities/emoji.rs index a0e8d14..2a38066 100644 --- a/src/types/entities/emoji.rs +++ b/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 pub struct Emoji { pub id: Option, pub name: Option, diff --git a/src/types/entities/guild_member.rs b/src/types/entities/guild_member.rs index 01f43de..b613800 100644 --- a/src/types/entities/guild_member.rs +++ b/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 pub struct GuildMember { pub user: Option, pub nick: Option, diff --git a/src/types/entities/message.rs b/src/types/entities/message.rs index 41d24b6..6e14a59 100644 --- a/src/types/entities/message.rs +++ b/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 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 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 pub struct MessageActivity { #[serde(rename = "type")] pub activity_type: i64, diff --git a/src/types/entities/sticker.rs b/src/types/entities/sticker.rs index 098394d..6263f48 100644 --- a/src/types/entities/sticker.rs +++ b/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 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 pub struct StickerItem { pub id: Snowflake, pub name: String,