From 282bc06cffa69fe57f6741518f080c799d64df6f Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Mon, 10 Jul 2023 16:59:00 +0200 Subject: [PATCH 01/26] /* -> /// --- src/api/channels/messages.rs | 41 +++++++++++++++----------------- src/api/channels/reactions.rs | 4 +--- src/api/users/users.rs | 18 +++++++------- src/instance.rs | 6 ++--- src/types/entities/attachment.rs | 6 +---- 5 files changed, 31 insertions(+), 44 deletions(-) diff --git a/src/api/channels/messages.rs b/src/api/channels/messages.rs index dbffaa8..c46409f 100644 --- a/src/api/channels/messages.rs +++ b/src/api/channels/messages.rs @@ -9,17 +9,15 @@ use crate::ratelimiter::ChorusRequest; use crate::types::{Message, MessageSendSchema, PartialDiscordFileAttachment, Snowflake}; impl Message { - /** - Sends a message to the Spacebar server. - # Arguments - * `url_api` - The URL of the Spacebar server's API. - * `message` - The [`Message`] that will be sent to the Spacebar server. - * `limits_user` - The [`Limits`] of the user. - * `limits_instance` - The [`Limits`] of the instance. - * `requester` - The [`LimitedRequester`] that will be used to make requests to the Spacebar server. - # Errors - * [`ChorusLibError`] - If the message cannot be sent. - */ + /// Sends a message to the Spacebar server. + /// # Arguments + /// * `url_api` - The URL of the Spacebar server's API. + /// * `message` - The [`Message`] that will be sent to the Spacebar server. + /// * `limits_user` - The [`Limits`] of the user. + /// * `limits_instance` - The [`Limits`] of the instance. + /// * `requester` - The [`LimitedRequester`] that will be used to make requests to the Spacebar server. + /// # Errors + /// * [`ChorusLibError`] - If the message cannot be sent. pub async fn send( user: &mut UserMeta, channel_id: Snowflake, @@ -78,18 +76,17 @@ impl Message { } impl UserMeta { + /// Sends a message to the Spacebar server. + /// # Arguments + /// * `url_api` - The URL of the Spacebar server's API. + /// * `message` - The [`Message`] that will be sent to the Spacebar server. + /// * `limits_user` - The [`Limits`] of the user. + /// * `limits_instance` - The [`Limits`] of the instance. + /// * `requester` - The [`LimitedRequester`] that will be used to make requests to the Spacebar server. + /// # Errors + /// * [`ChorusLibError`] - If the message cannot be sent. + /// # Notes /// Shorthand call for Message::send() - /** - Sends a message to the Spacebar server. - # Arguments - * `url_api` - The URL of the Spacebar server's API. - * `message` - The [`Message`] that will be sent to the Spacebar server. - * `limits_user` - The [`Limits`] of the user. - * `limits_instance` - The [`Limits`] of the instance. - * `requester` - The [`LimitedRequester`] that will be used to make requests to the Spacebar server. - # Errors - * [`ChorusLibError`] - If the message cannot be sent. - */ pub async fn send_message( &mut self, message: &mut MessageSendSchema, diff --git a/src/api/channels/reactions.rs b/src/api/channels/reactions.rs index 35dbb94..70c16ce 100644 --- a/src/api/channels/reactions.rs +++ b/src/api/channels/reactions.rs @@ -8,9 +8,7 @@ use crate::{ types::{self, PublicUser, Snowflake}, }; -/** -Useful metadata for working with [`types::Reaction`], bundled together nicely. - */ +/// Useful metadata for working with [`types::Reaction`], bundled together nicely. pub struct ReactionMeta { pub message_id: types::Snowflake, pub channel_id: types::Snowflake, diff --git a/src/api/users/users.rs b/src/api/users/users.rs index bd46a36..7c67c7d 100644 --- a/src/api/users/users.rs +++ b/src/api/users/users.rs @@ -140,16 +140,14 @@ impl User { } impl Instance { - /** - Get a user object by id, or get the current user. - # Arguments - * `token` - A valid access token for the API. - * `id` - The id of the user that will be retrieved. If this is None, the current user will be retrieved. - # Errors - * [`ChorusLibError`] - If the request fails. - # Notes - This function is a wrapper around [`User::get`]. - */ + // Get a user object by id, or get the current user. + // # Arguments + // * `token` - A valid access token for the API. + // * `id` - The id of the user that will be retrieved. If this is None, the current user will be retrieved. + // # Errors + // * [`ChorusLibError`] - If the request fails. + // # Notes + // This function is a wrapper around [`User::get`]. pub async fn get_user(&mut self, token: String, id: Option<&String>) -> ChorusResult { let mut user = UserMeta::shell(Rc::new(RefCell::new(self.clone())), token); let result = User::get(&mut user, id).await; diff --git a/src/instance.rs b/src/instance.rs index 15c513c..d40d900 100644 --- a/src/instance.rs +++ b/src/instance.rs @@ -14,10 +14,8 @@ use crate::types::{GeneralConfiguration, User, UserSettings}; use crate::UrlBundle; #[derive(Debug, Clone)] -/** -The [`Instance`] what you will be using to perform all sorts of actions on the Spacebar server. -If `limits_information` is `None`, then the instance will not be rate limited. - */ +/// The [`Instance`]; what you will be using to perform all sorts of actions on the Spacebar server. +/// If `limits_information` is `None`, then the instance will not be rate limited. pub struct Instance { pub urls: UrlBundle, pub instance_info: GeneralConfiguration, diff --git a/src/types/entities/attachment.rs b/src/types/entities/attachment.rs index 7bd9d2b..4261203 100644 --- a/src/types/entities/attachment.rs +++ b/src/types/entities/attachment.rs @@ -41,11 +41,7 @@ pub struct PartialDiscordFileAttachment { } impl PartialDiscordFileAttachment { - /** - Moves `self.content` out of `self` and returns it. - # Returns - Vec - */ + /// Moves `self.content` out of `self` and returns it. pub fn move_content(self) -> (Vec, PartialDiscordFileAttachment) { let content = self.content; let updated_struct = PartialDiscordFileAttachment { From 832cb92abc464e5d2cf322dd8f7dced15ac107a6 Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Mon, 10 Jul 2023 17:22:31 +0200 Subject: [PATCH 02/26] UrlBundle slightly better docs --- src/lib.rs | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index 77425b8..5b14544 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -18,9 +18,18 @@ pub mod voice; #[derive(Clone, Default, Debug, PartialEq, Eq)] /// A URLBundle is a struct which bundles together the API-, Gateway- and CDN-URLs of a Spacebar /// instance. +/// # Notes +/// All the urls can be found on the /api/policies/instance/domains endpoint of a spacebar server pub struct UrlBundle { + /// The api's url. + /// Ex: `https://old.server.spacebar.chat/api` pub api: String, + /// The gateway websocket url. + /// Note that because this is a websocket url, it will always start with `wss://` + /// Ex: `wss://gateway.old.server.spacebar.chat` pub wss: String, + /// The CDN's url. + /// Ex: `https://cdn.old.server.spacebar.chat` pub cdn: String, } From 133021a805ef5cd6e70c199661c9c3154d9ef1ae Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Mon, 10 Jul 2023 18:06:45 +0200 Subject: [PATCH 03/26] Rustdoc warnings + misc changes --- src/api/auth/register.rs | 2 +- src/api/channels/messages.rs | 15 +++------ src/api/channels/reactions.rs | 20 ++++++------ src/api/guilds/member.rs | 12 +++---- src/api/guilds/roles.rs | 32 ++++--------------- src/api/policies/instance/instance.rs | 2 +- src/api/policies/instance/ratelimits.rs | 2 -- src/api/users/relationships.rs | 12 ++++--- src/api/users/users.rs | 9 +++--- src/gateway.rs | 4 +-- src/instance.rs | 7 +---- src/types/entities/application.rs | 6 ++-- src/types/entities/audit_log.rs | 4 +-- src/types/entities/auto_moderation.rs | 28 ++++++++--------- src/types/entities/guild.rs | 16 +++++----- src/types/entities/integration.rs | 4 +-- src/types/entities/relationship.rs | 4 +-- src/types/entities/role.rs | 4 +-- src/types/entities/stage_instance.rs | 6 ++-- src/types/entities/template.rs | 2 +- src/types/entities/voice_state.rs | 2 +- src/types/entities/webhook.rs | 2 +- src/types/events/application.rs | 2 +- src/types/events/auto_moderation.rs | 8 ++--- src/types/events/call.rs | 2 +- src/types/events/channel.rs | 10 +++--- src/types/events/guild.rs | 42 ++++++++++++------------- src/types/events/integration.rs | 6 ++-- src/types/events/interaction.rs | 2 +- src/types/events/invite.rs | 4 +-- src/types/events/lazy_request.rs | 2 +- src/types/events/message.rs | 6 ++-- src/types/events/mod.rs | 5 +-- src/types/events/presence.rs | 4 +-- src/types/events/ready.rs | 4 +-- src/types/events/relationship.rs | 4 +-- src/types/events/request_members.rs | 2 +- src/types/events/stage_instance.rs | 6 ++-- src/types/events/thread.rs | 12 +++---- src/types/events/user.rs | 2 +- src/types/events/voice.rs | 4 +-- src/types/events/webhooks.rs | 2 +- src/types/interfaces/status.rs | 2 +- src/types/utils/snowflake.rs | 2 +- 44 files changed, 147 insertions(+), 181 deletions(-) diff --git a/src/api/auth/register.rs b/src/api/auth/register.rs index a6849cc..e7b9d48 100644 --- a/src/api/auth/register.rs +++ b/src/api/auth/register.rs @@ -20,7 +20,7 @@ impl Instance { /// /// # Errors /// - /// * [`ChorusLibError`] - If the server does not respond. + /// * [`crate::errors::ChorusError`] - If the server does not respond. pub async fn register_account( &mut self, register_schema: &RegisterSchema, diff --git a/src/api/channels/messages.rs b/src/api/channels/messages.rs index c46409f..73afda9 100644 --- a/src/api/channels/messages.rs +++ b/src/api/channels/messages.rs @@ -4,6 +4,7 @@ use reqwest::{multipart, Client}; use serde_json::to_string; use crate::api::LimitType; +use crate::errors::ChorusResult; use crate::instance::UserMeta; use crate::ratelimiter::ChorusRequest; use crate::types::{Message, MessageSendSchema, PartialDiscordFileAttachment, Snowflake}; @@ -13,17 +14,14 @@ impl Message { /// # Arguments /// * `url_api` - The URL of the Spacebar server's API. /// * `message` - The [`Message`] that will be sent to the Spacebar server. - /// * `limits_user` - The [`Limits`] of the user. - /// * `limits_instance` - The [`Limits`] of the instance. - /// * `requester` - The [`LimitedRequester`] that will be used to make requests to the Spacebar server. /// # Errors - /// * [`ChorusLibError`] - If the message cannot be sent. + /// * [`crate::errors::ChorusError`] - If the message cannot be sent. pub async fn send( user: &mut UserMeta, channel_id: Snowflake, message: &mut MessageSendSchema, files: Option>, - ) -> Result { + ) -> ChorusResult { let url_api = user.belongs_to.borrow().urls.api.clone(); if files.is_none() { @@ -80,11 +78,8 @@ impl UserMeta { /// # Arguments /// * `url_api` - The URL of the Spacebar server's API. /// * `message` - The [`Message`] that will be sent to the Spacebar server. - /// * `limits_user` - The [`Limits`] of the user. - /// * `limits_instance` - The [`Limits`] of the instance. - /// * `requester` - The [`LimitedRequester`] that will be used to make requests to the Spacebar server. /// # Errors - /// * [`ChorusLibError`] - If the message cannot be sent. + /// * [`crate::errors::ChorusError`] - If the message cannot be sent. /// # Notes /// Shorthand call for Message::send() pub async fn send_message( @@ -92,7 +87,7 @@ impl UserMeta { message: &mut MessageSendSchema, channel_id: Snowflake, files: Option>, - ) -> Result { + ) -> ChorusResult { Message::send(self, channel_id, message, files).await } } diff --git a/src/api/channels/reactions.rs b/src/api/channels/reactions.rs index 70c16ce..fe1e57f 100644 --- a/src/api/channels/reactions.rs +++ b/src/api/channels/reactions.rs @@ -20,10 +20,10 @@ impl ReactionMeta { /// # Arguments /// * `user` - A mutable reference to a [`UserMeta`] instance. /// # Returns - /// A `Result` [`()`] [`crate::errors::ChorusLibError`] if something went wrong. + /// A `Result` [`()`] [`crate::errors::ChorusError`] if something went wrong. /// Fires a `Message Reaction Remove All` Gateway event. /// # Reference - /// See [https://discord.com/developers/docs/resources/channel#delete-all-reactions](https://discord.com/developers/docs/resources/channel#delete-all-reactions) + /// See pub async fn delete_all(&self, user: &mut UserMeta) -> ChorusResult<()> { let url = format!( "{}/channels/{}/messages/{}/reactions/", @@ -47,7 +47,7 @@ impl ReactionMeta { /// # Returns /// A Result that is [`Err(crate::errors::ChorusLibError)`] if something went wrong. /// # Reference - /// See [https://discord.com/developers/docs/resources/channel#get-reactions](https://discord.com/developers/docs/resources/channel#get-reactions) + /// See pub async fn get(&self, emoji: &str, user: &mut UserMeta) -> ChorusResult> { let url = format!( "{}/channels/{}/messages/{}/reactions/{}/", @@ -76,7 +76,7 @@ impl ReactionMeta { /// A Result that is [`Err(crate::errors::ChorusLibError)`] if something went wrong. /// Fires a `Message Reaction Remove Emoji` Gateway event. /// # Reference - /// See [https://discord.com/developers/docs/resources/channel#delete-all-reactions-for-emoji](https://discord.com/developers/docs/resources/channel#delete-all-reactions-for-emoji) + /// See pub async fn delete_emoji(&self, emoji: &str, user: &mut UserMeta) -> ChorusResult<()> { let url = format!( "{}/channels/{}/messages/{}/reactions/{}/", @@ -103,9 +103,9 @@ impl ReactionMeta { /// format name:id with the emoji name and emoji id. /// * `user` - A mutable reference to a [`UserMeta`] instance. /// # Returns - /// A `Result` containing [`()`] or a [`crate::errors::ChorusLibError`]. + /// A `Result` containing [`()`] or a [`crate::errors::ChorusError`]. /// # Reference - /// See [https://discord.com/developers/docs/resources/channel#create-reaction](https://discord.com/developers/docs/resources/channel#create-reaction) + /// See /// pub async fn create(&self, emoji: &str, user: &mut UserMeta) -> ChorusResult<()> { let url = format!( @@ -129,10 +129,10 @@ impl ReactionMeta { /// format name:id with the emoji name and emoji id. /// * `user` - A mutable reference to a [`UserMeta`] instance. /// # Returns - /// A `Result` containing [`()`] or a [`crate::errors::ChorusLibError`]. + /// A `Result` containing [`()`] or a [`crate::errors::ChorusError`]. /// Fires a `Message Reaction Remove` Gateway event. /// # Reference - /// See [https://discord.com/developers/docs/resources/channel#delete-own-reaction](https://discord.com/developers/docs/resources/channel#delete-own-reaction) + /// See pub async fn remove(&self, emoji: &str, user: &mut UserMeta) -> ChorusResult<()> { let url = format!( "{}/channels/{}/messages/{}/reactions/{}/@me/", @@ -157,10 +157,10 @@ impl ReactionMeta { /// format name:id with the emoji name and emoji id. /// * `user` - A mutable reference to a [`UserMeta`] instance. /// # Returns - /// A `Result` containing [`()`] or a [`crate::errors::ChorusLibError`]. + /// A [`ChorusResult`] containing [`()`] or a [`crate::errors::ChorusError`]. /// Fires a Message Reaction Remove Gateway event. /// # Reference - /// See [https://discord.com/developers/docs/resources/channel#delete-own-reaction](https://discord.com/developers/docs/resources/channel#delete-own-reaction) + /// See pub async fn delete_user( &self, user_id: Snowflake, diff --git a/src/api/guilds/member.rs b/src/api/guilds/member.rs index 5fa99cd..c7e26b9 100644 --- a/src/api/guilds/member.rs +++ b/src/api/guilds/member.rs @@ -5,7 +5,7 @@ use crate::{ errors::ChorusResult, instance::UserMeta, ratelimiter::ChorusRequest, - types::{self, Snowflake}, + types::{self, GuildMember, Snowflake}, }; impl types::GuildMember { @@ -19,12 +19,12 @@ impl types::GuildMember { /// /// # Returns /// - /// A [`Result`] containing a [`GuildMember`] if the request succeeds, or a [`ChorusLibError`] if the request fails. + /// A [`ChorusResult`] containing a [`GuildMember`] if the request succeeds. pub async fn get( user: &mut UserMeta, guild_id: Snowflake, member_id: Snowflake, - ) -> ChorusResult { + ) -> ChorusResult { let url = format!( "{}/guilds/{}/members/{}/", user.belongs_to.borrow().urls.api, @@ -36,7 +36,7 @@ impl types::GuildMember { limit_type: LimitType::Guild(guild_id), }; chorus_request - .deserialize_response::(user) + .deserialize_response::(user) .await } @@ -51,7 +51,7 @@ impl types::GuildMember { /// /// # Returns /// - /// An `Result` containing a `ChorusLibError` if the request fails, or `()` if the request succeeds. + /// A [`ChorusResult`] containing a [`crate::errors::ChorusError`] if the request fails, or `()` if the request succeeds. pub async fn add_role( user: &mut UserMeta, guild_id: Snowflake, @@ -83,7 +83,7 @@ impl types::GuildMember { /// /// # Returns /// - /// A `Result` containing a `ChorusLibError` if the request fails, or `()` if the request succeeds. + /// A [`ChorusResult`] containing a [`crate::errors::ChorusError`] if the request fails, or `()` if the request succeeds. pub async fn remove_role( user: &mut UserMeta, guild_id: Snowflake, diff --git a/src/api/guilds/roles.rs b/src/api/guilds/roles.rs index 1d1bc68..f8cade9 100644 --- a/src/api/guilds/roles.rs +++ b/src/api/guilds/roles.rs @@ -6,7 +6,7 @@ use crate::{ errors::{ChorusError, ChorusResult}, instance::UserMeta, ratelimiter::ChorusRequest, - types::{self, RoleCreateModifySchema, RoleObject, Snowflake}, + types::{self, RoleCreateModifySchema, RoleObject, RolePositionUpdateSchema, Snowflake}, }; impl types::RoleObject { @@ -20,10 +20,6 @@ impl types::RoleObject { /// # Returns /// /// An `Option` containing a `Vec` of [`RoleObject`]s if roles were found, or `None` if no roles were found. - /// - /// # Errors - /// - /// Returns a [`ChorusLibError`] if the request fails or if the response is invalid. pub async fn get_all( user: &mut UserMeta, guild_id: Snowflake, @@ -57,11 +53,7 @@ impl types::RoleObject { /// /// # Returns /// - /// A `Result` containing the retrieved [`RoleObject`] if successful, or a [`ChorusLibError`] if the request fails or if the response is invalid. - /// - /// # Errors - /// - /// Returns a [`ChorusLibError`] if the request fails or if the response is invalid. + /// A `Result` containing the retrieved [`RoleObject`] if successful, or a [`ChorusError`] if the request fails or if the response is invalid. pub async fn get( user: &mut UserMeta, guild_id: Snowflake, @@ -92,11 +84,7 @@ impl types::RoleObject { /// /// # Returns /// - /// A `Result` containing the newly created [`RoleObject`] if successful, or a [`ChorusLibError`] if the request fails or if the response is invalid. - /// - /// # Errors - /// - /// Returns a [`ChorusLibError`] if the request fails or if the response is invalid. + /// A `Result` containing the newly created [`RoleObject`] if successful, or a [`ChorusError`] if the request fails or if the response is invalid. pub async fn create( user: &mut UserMeta, guild_id: Snowflake, @@ -131,15 +119,11 @@ impl types::RoleObject { /// /// # Returns /// - /// A `Result` containing the updated [`RoleObject`] if successful, or a [`ChorusLibError`] if the request fails or if the response is invalid. - /// - /// # Errors - /// - /// Returns a [`ChorusLibError`] if the request fails or if the response is invalid. + /// A `Result` containing the updated [`RoleObject`] if successful, or a [`ChorusError`] if the request fails or if the response is invalid. pub async fn position_update( user: &mut UserMeta, guild_id: Snowflake, - role_position_update_schema: types::RolePositionUpdateSchema, + role_position_update_schema: RolePositionUpdateSchema, ) -> ChorusResult { let url = format!( "{}/guilds/{}/roles/", @@ -173,11 +157,7 @@ impl types::RoleObject { /// /// # Returns /// - /// A `Result` containing the updated [`RoleObject`] if successful, or a [`ChorusLibError`] if the request fails or if the response is invalid. - /// - /// # Errors - /// - /// Returns a [`ChorusLibError`] if the request fails or if the response is invalid. + /// A `Result` containing the updated [`RoleObject`] if successful, or a [`ChorusError`] if the request fails or if the response is invalid. pub async fn update( user: &mut UserMeta, guild_id: Snowflake, diff --git a/src/api/policies/instance/instance.rs b/src/api/policies/instance/instance.rs index 75f832c..d015778 100644 --- a/src/api/policies/instance/instance.rs +++ b/src/api/policies/instance/instance.rs @@ -7,7 +7,7 @@ use crate::types::GeneralConfiguration; impl Instance { /// Gets the instance policies schema. /// # Errors - /// [`ChorusLibError`] - If the request fails. + /// [`ChorusError`] - If the request fails. 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/policies/instance/ratelimits.rs b/src/api/policies/instance/ratelimits.rs index 125af32..5e7def7 100644 --- a/src/api/policies/instance/ratelimits.rs +++ b/src/api/policies/instance/ratelimits.rs @@ -22,8 +22,6 @@ pub enum LimitType { } /// A struct that represents the current ratelimits, either instance-wide or user-wide. -/// Unlike [`RateLimits`], this struct shows the current ratelimits, not the rate limit -/// configuration for the instance. /// See for more information. #[derive(Debug, Clone)] pub struct Limit { diff --git a/src/api/users/relationships.rs b/src/api/users/relationships.rs index 39c75d8..a864706 100644 --- a/src/api/users/relationships.rs +++ b/src/api/users/relationships.rs @@ -6,7 +6,9 @@ use crate::{ errors::ChorusResult, instance::UserMeta, ratelimiter::ChorusRequest, - types::{self, CreateUserRelationshipSchema, RelationshipType, Snowflake}, + types::{ + self, CreateUserRelationshipSchema, FriendRequestSendSchema, RelationshipType, Snowflake, + }, }; impl UserMeta { @@ -61,10 +63,10 @@ impl UserMeta { /// * `schema` - A [`FriendRequestSendSchema`] struct that holds the information about the friend request to be sent. /// /// # Returns - /// This function returns a [`Result`] that holds a [`ChorusLibError`] if the request fails. + /// This function returns a [`ChorusResult`]. pub async fn send_friend_request( &mut self, - schema: types::FriendRequestSendSchema, + schema: FriendRequestSendSchema, ) -> ChorusResult<()> { let url = format!( "{}/users/@me/relationships/", @@ -91,7 +93,7 @@ impl UserMeta { /// * [`RelationshipType::Blocked`]: Blocks the specified user_id. /// /// # Returns - /// This function returns an [`Result`] that holds a [`ChorusLibError`] if the request fails. + /// This function returns an [`ChorusResult`]. pub async fn modify_user_relationship( &mut self, user_id: Snowflake, @@ -149,7 +151,7 @@ impl UserMeta { /// * `user_id` - ID of the user to remove the relationship with. /// /// # Returns - /// This function returns a [`Result`] that holds a [`ChorusLibError`] if the request fails. + /// This function returns a [`ChorusResult`]. pub async fn remove_relationship(&mut self, user_id: Snowflake) -> ChorusResult<()> { let url = format!( "{}/users/@me/relationships/{}/", diff --git a/src/api/users/users.rs b/src/api/users/users.rs index 7c67c7d..0f6a5ee 100644 --- a/src/api/users/users.rs +++ b/src/api/users/users.rs @@ -19,11 +19,10 @@ impl UserMeta { /// * `token` - A valid access token for the API. /// * `url_api` - The URL to the API. /// * `id` - The id of the user that will be retrieved. If this is None, the current user will be retrieved. - /// * `instance_limits` - The [`Limits`] of the instance. /// /// # Errors /// - /// * [`ChorusLibError`] - If the request fails. + /// * [`ChorusError`] - If the request fails. pub async fn get(user: &mut UserMeta, id: Option<&String>) -> ChorusResult { User::get(user, id).await } @@ -44,7 +43,7 @@ impl UserMeta { /// /// # Errors /// - /// Returns an `ChorusLibError` if the request fails or if a password is required but not provided. + /// Returns an [`ChorusError`] if the request fails or if a password is required but not provided. pub async fn modify(&mut self, modify_schema: UserModifySchema) -> ChorusResult { if modify_schema.new_password.is_some() || modify_schema.email.is_some() @@ -76,7 +75,7 @@ impl UserMeta { /// /// # Returns /// - /// Returns `()` if the user was successfully deleted, or a `ChorusLibError` if an error occurred. + /// Returns `()` if the user was successfully deleted, or a [`ChorusError`] if an error occurred. pub async fn delete(mut self) -> ChorusResult<()> { let request = Client::new() .post(format!( @@ -145,7 +144,7 @@ impl Instance { // * `token` - A valid access token for the API. // * `id` - The id of the user that will be retrieved. If this is None, the current user will be retrieved. // # Errors - // * [`ChorusLibError`] - If the request fails. + // * [`ChorusError`] - If the request fails. // # Notes // This function is a wrapper around [`User::get`]. pub async fn get_user(&mut self, token: String, id: Option<&String>) -> ChorusResult { diff --git a/src/gateway.rs b/src/gateway.rs index ed96aac..3e6a604 100644 --- a/src/gateway.rs +++ b/src/gateway.rs @@ -72,7 +72,7 @@ const GATEWAY_LAZY_REQUEST: u8 = 14; /// The amount of time we wait for a heartbeat ack before resending our heartbeat in ms const HEARTBEAT_ACK_TIMEOUT: u128 = 2000; -/// Represents a messsage received from the gateway. This will be either a [GatewayReceivePayload], containing events, or a [GatewayError]. +/// Represents a messsage received from the gateway. This will be either a [types::GatewayReceivePayload], containing events, or a [GatewayError]. /// This struct is used internally when handling messages. #[derive(Clone, Debug)] pub struct GatewayMessage { @@ -144,7 +144,7 @@ impl GatewayMessage { /// Represents a handle to a Gateway connection. A Gateway connection will create observable /// [`GatewayEvents`](GatewayEvent), which you can subscribe to. Gateway events include all currently -/// implemented [Types] with the trait [`WebSocketEvent`] +/// implemented types with the trait [`WebSocketEvent`] /// Using this handle you can also send Gateway Events directly. #[derive(Debug)] pub struct GatewayHandle { diff --git a/src/instance.rs b/src/instance.rs index d40d900..f7d2c2a 100644 --- a/src/instance.rs +++ b/src/instance.rs @@ -30,12 +30,7 @@ pub struct LimitsInformation { } impl Instance { - /// Creates a new [`Instance`]. - /// # Arguments - /// * `urls` - The [`URLBundle`] that contains all the URLs that are needed to connect to the Spacebar server. - /// * `requester` - The [`LimitedRequester`] that will be used to make requests to the Spacebar server. - /// # Errors - /// * [`InstanceError`] - If the instance cannot be created. + /// Creates a new [`Instance`] from the [relevant instance urls](UrlBundle), where `limited` is whether or not to automatically use rate limits. pub async fn new(urls: UrlBundle, limited: bool) -> ChorusResult { let limits_information; if limited { diff --git a/src/types/entities/application.rs b/src/types/entities/application.rs index 6cac20b..15e259c 100644 --- a/src/types/entities/application.rs +++ b/src/types/entities/application.rs @@ -168,7 +168,7 @@ pub struct ApplicationCommandInteractionDataOption { } #[derive(Debug, Default, Clone, PartialEq, Serialize, Deserialize)] -/// See https://discord.com/developers/docs/interactions/application-commands#application-command-permissions-object-guild-application-command-permissions-structure +/// See pub struct GuildApplicationCommandPermissions { pub id: Snowflake, pub application_id: Snowflake, @@ -177,7 +177,7 @@ pub struct GuildApplicationCommandPermissions { } #[derive(Debug, Default, Clone, PartialEq, Serialize, Deserialize)] -/// See https://discord.com/developers/docs/interactions/application-commands#application-command-permissions-object-application-command-permissions-structure +/// See pub struct ApplicationCommandPermission { pub id: Snowflake, #[serde(rename = "type")] @@ -189,7 +189,7 @@ pub struct ApplicationCommandPermission { #[derive(Serialize_repr, Deserialize_repr, Debug, Default, Clone, PartialEq)] #[serde(rename_all = "SCREAMING_SNAKE_CASE")] #[repr(u8)] -/// See https://discord.com/developers/docs/interactions/application-commands#application-command-permissions-object-application-command-permission-type +/// See pub enum ApplicationCommandPermissionType { #[default] Role = 1, diff --git a/src/types/entities/audit_log.rs b/src/types/entities/audit_log.rs index 1e04e8b..8965a05 100644 --- a/src/types/entities/audit_log.rs +++ b/src/types/entities/audit_log.rs @@ -3,7 +3,7 @@ use serde::{Deserialize, Serialize}; use crate::types::utils::Snowflake; #[derive(Serialize, Deserialize, Debug, Default, Clone)] -/// See https://discord.com/developers/docs/resources/audit-log#audit-log-entry-object +/// See pub struct AuditLogEntry { pub target_id: Option, pub changes: Option>, @@ -17,7 +17,7 @@ pub struct AuditLogEntry { } #[derive(Serialize, Deserialize, Debug, Default, Clone)] -/// See https://discord.com/developers/docs/resources/audit-log#audit-log-change-object +/// See pub struct AuditLogChange { pub new_value: Option, pub old_value: Option, diff --git a/src/types/entities/auto_moderation.rs b/src/types/entities/auto_moderation.rs index 144aa4b..0feadde 100644 --- a/src/types/entities/auto_moderation.rs +++ b/src/types/entities/auto_moderation.rs @@ -4,7 +4,7 @@ use serde_repr::{Deserialize_repr, Serialize_repr}; use crate::types::utils::Snowflake; #[derive(Serialize, Deserialize, Debug, Default, Clone)] -/// See https://discord.com/developers/docs/resources/auto-moderation#auto-moderation-rule-object +/// See pub struct AutoModerationRule { pub id: Snowflake, pub guild_id: Snowflake, @@ -22,7 +22,7 @@ pub struct AutoModerationRule { #[derive(Serialize_repr, Deserialize_repr, Debug, Clone, Default)] #[repr(u8)] #[serde(rename_all = "SCREAMING_SNAKE_CASE")] -/// See https://discord.com/developers/docs/resources/auto-moderation#auto-moderation-rule-object-event-types +/// See pub enum AutoModerationRuleEventType { #[default] MessageSend = 1, @@ -31,7 +31,7 @@ pub enum AutoModerationRuleEventType { #[derive(Serialize_repr, Deserialize_repr, Debug, Clone, Default)] #[repr(u8)] #[serde(rename_all = "SCREAMING_SNAKE_CASE")] -/// See https://discord.com/developers/docs/resources/auto-moderation#auto-moderation-rule-object-trigger-types +/// See pub enum AutoModerationRuleTriggerType { #[default] Keyword = 1, @@ -42,7 +42,7 @@ pub enum AutoModerationRuleTriggerType { #[derive(Serialize, Deserialize, Debug, Clone, Default)] #[serde(untagged)] -/// See https://discord.com/developers/docs/resources/auto-moderation#auto-moderation-rule-object-trigger-metadata +/// See pub enum AutoModerationRuleTriggerMetadata { ForKeyword(AutoModerationRuleTriggerMetadataForKeyword), ForKeywordPreset(AutoModerationRuleTriggerMetadataForKeywordPreset), @@ -52,7 +52,7 @@ pub enum AutoModerationRuleTriggerMetadata { } #[derive(Serialize, Deserialize, Debug, Clone, Default)] -/// See https://discord.com/developers/docs/resources/auto-moderation#auto-moderation-rule-object-trigger-metadata +/// See pub struct AutoModerationRuleTriggerMetadataForKeyword { pub keyword_filter: Vec, pub regex_patterns: Vec, @@ -60,14 +60,14 @@ pub struct AutoModerationRuleTriggerMetadataForKeyword { } #[derive(Serialize, Deserialize, Debug, Clone, Default)] -/// See https://discord.com/developers/docs/resources/auto-moderation#auto-moderation-rule-object-trigger-metadata +/// See pub struct AutoModerationRuleTriggerMetadataForKeywordPreset { pub presets: Vec, pub allow_list: Vec, } #[derive(Serialize, Deserialize, Debug, Clone, Default)] -/// See https://discord.com/developers/docs/resources/auto-moderation#auto-moderation-rule-object-trigger-metadata +/// See pub struct AutoModerationRuleTriggerMetadataForMentionSpam { /// Max 50 pub mention_total_limit: u8, @@ -77,7 +77,7 @@ pub struct AutoModerationRuleTriggerMetadataForMentionSpam { #[derive(Serialize_repr, Deserialize_repr, Debug, Clone, Default)] #[repr(u8)] #[serde(rename_all = "SCREAMING_SNAKE_CASE")] -/// See https://discord.com/developers/docs/resources/auto-moderation#auto-moderation-rule-object-keyword-preset-types +/// See pub enum AutoModerationRuleKeywordPresetType { #[default] Profanity = 1, @@ -86,7 +86,7 @@ pub enum AutoModerationRuleKeywordPresetType { } #[derive(Serialize, Deserialize, Debug, Clone, Default)] -/// See https://discord.com/developers/docs/resources/auto-moderation#auto-moderation-action-object +/// See pub struct AutoModerationAction { #[serde(rename = "type")] pub action_type: AutoModerationActionType, @@ -96,7 +96,7 @@ pub struct AutoModerationAction { #[derive(Serialize_repr, Deserialize_repr, Debug, Clone, Default)] #[repr(u8)] #[serde(rename_all = "SCREAMING_SNAKE_CASE")] -/// See https://discord.com/developers/docs/resources/auto-moderation#auto-moderation-action-object-action-types +/// See pub enum AutoModerationActionType { #[default] BlockMessage = 1, @@ -106,7 +106,7 @@ pub enum AutoModerationActionType { #[derive(Serialize, Deserialize, Debug, Clone, Default)] #[serde(untagged)] -/// See https://discord.com/developers/docs/resources/auto-moderation#auto-moderation-action-object-action-metadata +/// See pub enum AutoModerationActionMetadata { ForBlockMessage(AutoModerationActionMetadataForBlockMessage), ForSendAlertMessage(AutoModerationActionMetadataForSendAlertMessage), @@ -116,19 +116,19 @@ pub enum AutoModerationActionMetadata { } #[derive(Serialize, Deserialize, Debug, Clone, Default)] -/// See https://discord.com/developers/docs/resources/auto-moderation#auto-moderation-action-object-action-metadata +/// See pub struct AutoModerationActionMetadataForBlockMessage { pub custom_message: Option, } #[derive(Serialize, Deserialize, Debug, Clone, Default)] -/// See https://discord.com/developers/docs/resources/auto-moderation#auto-moderation-action-object-action-metadata +/// See pub struct AutoModerationActionMetadataForSendAlertMessage { pub channel_id: Snowflake, } #[derive(Serialize, Deserialize, Debug, Clone, Default)] -/// See https://discord.com/developers/docs/resources/auto-moderation#auto-moderation-action-object-action-metadata +/// See pub struct AutoModerationActionMetadataForTimeout { /// Max 2419200 pub duration_seconds: u32, diff --git a/src/types/entities/guild.rs b/src/types/entities/guild.rs index 857ed2a..5c8eaf0 100644 --- a/src/types/entities/guild.rs +++ b/src/types/entities/guild.rs @@ -9,7 +9,7 @@ use crate::types::{ utils::Snowflake, }; -/// See https://discord.com/developers/docs/resources/guild +/// See #[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq)] #[cfg_attr(feature = "sqlx", derive(sqlx::FromRow))] pub struct Guild { @@ -90,7 +90,7 @@ pub struct Guild { pub widget_enabled: Option, } -/// See https://docs.spacebar.chat/routes/#get-/guilds/-guild_id-/bans/-user- +/// See #[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq)] #[cfg_attr(feature = "sqlx", derive(sqlx::FromRow))] pub struct GuildBan { @@ -99,7 +99,7 @@ pub struct GuildBan { pub reason: Option, } -/// See https://docs.spacebar.chat/routes/#cmp--schemas-invite +/// See #[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq)] #[cfg_attr(feature = "sqlx", derive(sqlx::FromRow))] pub struct GuildInvite { @@ -134,7 +134,7 @@ pub struct GuildCreateResponse { } #[derive(Serialize, Deserialize, Debug, Default, Clone)] -/// See https://discord.com/developers/docs/resources/guild-scheduled-event#guild-scheduled-event-object +/// See pub struct GuildScheduledEvent { pub id: Snowflake, pub guild_id: Snowflake, @@ -156,7 +156,7 @@ pub struct GuildScheduledEvent { #[derive(Serialize_repr, Deserialize_repr, Debug, Default, Clone)] #[repr(u8)] -/// See https://discord.com/developers/docs/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-privacy-level +/// See pub enum GuildScheduledEventPrivacyLevel { #[default] GuildOnly = 2, @@ -164,7 +164,7 @@ pub enum GuildScheduledEventPrivacyLevel { #[derive(Serialize_repr, Deserialize_repr, Debug, Default, Clone)] #[repr(u8)] -/// See https://discord.com/developers/docs/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-status +/// See pub enum GuildScheduledEventStatus { #[default] Scheduled = 1, @@ -175,7 +175,7 @@ pub enum GuildScheduledEventStatus { #[derive(Serialize_repr, Deserialize_repr, Debug, Default, Clone)] #[repr(u8)] -/// See https://discord.com/developers/docs/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-entity-types +/// See pub enum GuildScheduledEventEntityType { #[default] StageInstance = 1, @@ -184,7 +184,7 @@ pub enum GuildScheduledEventEntityType { } #[derive(Serialize, Deserialize, Debug, Default, Clone)] -/// See https://discord.com/developers/docs/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-entity-metadata +/// See pub struct GuildScheduledEventEntityMetadata { pub location: Option, } diff --git a/src/types/entities/integration.rs b/src/types/entities/integration.rs index 8076e70..f083dae 100644 --- a/src/types/entities/integration.rs +++ b/src/types/entities/integration.rs @@ -8,7 +8,7 @@ use crate::types::{ #[derive(Default, Debug, Deserialize, Serialize, Clone)] #[cfg_attr(feature = "sqlx", derive(sqlx::FromRow))] -/// See https://discord.com/developers/docs/resources/guild#integration-object-integration-structure +/// See pub struct Integration { pub id: Snowflake, pub name: String, @@ -33,7 +33,7 @@ pub struct Integration { } #[derive(Default, Debug, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/resources/guild#integration-account-object-integration-account-structure +/// See pub struct IntegrationAccount { pub id: String, pub name: String, diff --git a/src/types/entities/relationship.rs b/src/types/entities/relationship.rs index a6abc09..168f362 100644 --- a/src/types/entities/relationship.rs +++ b/src/types/entities/relationship.rs @@ -7,7 +7,7 @@ use crate::types::Snowflake; use super::PublicUser; #[derive(Debug, Deserialize, Serialize, Clone, Default, PartialEq, Eq)] -/// See https://discord-userdoccers.vercel.app/resources/user#relationship-structure +/// See pub struct Relationship { pub id: Snowflake, #[serde(rename = "type")] @@ -19,7 +19,7 @@ pub struct Relationship { #[derive(Serialize_repr, Deserialize_repr, Debug, Clone, Default, Eq, PartialEq)] #[repr(u8)] -/// See https://discord-userdoccers.vercel.app/resources/user#relationship-type +/// See pub enum RelationshipType { Suggestion = 6, Implicit = 5, diff --git a/src/types/entities/role.rs b/src/types/entities/role.rs index 1719d28..ef93b5d 100644 --- a/src/types/entities/role.rs +++ b/src/types/entities/role.rs @@ -6,7 +6,7 @@ use crate::types::utils::Snowflake; #[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq)] #[cfg_attr(feature = "sqlx", derive(sqlx::FromRow))] -/// See https://discord.com/developers/docs/topics/permissions#role-object +/// See pub struct RoleObject { pub id: Snowflake, pub name: String, @@ -35,7 +35,7 @@ pub struct RoleSubscriptionData { } #[derive(Serialize, Deserialize, Debug, Default, Clone, Eq, PartialEq)] -/// See https://discord.com/developers/docs/topics/permissions#role-object-role-tags-structure +/// See pub struct RoleTags { #[serde(default)] #[serde(deserialize_with = "deserialize_option_number_from_string")] diff --git a/src/types/entities/stage_instance.rs b/src/types/entities/stage_instance.rs index b2d19c3..8810f52 100644 --- a/src/types/entities/stage_instance.rs +++ b/src/types/entities/stage_instance.rs @@ -4,12 +4,12 @@ use serde_repr::{Deserialize_repr, Serialize_repr}; use crate::types::Snowflake; #[derive(Serialize, Deserialize, Debug, Default, Clone)] -/// See https://discord.com/developers/docs/resources/stage-instance +/// See pub struct StageInstance { pub id: Snowflake, pub guild_id: Snowflake, pub channel_id: Snowflake, - /// 1 - 120 chars + /// 1 - 120 characters pub topic: String, pub privacy_level: StageInstancePrivacyLevel, /// deprecated, apparently @@ -20,7 +20,7 @@ pub struct StageInstance { #[derive(Serialize_repr, Deserialize_repr, Debug, Clone, Default)] #[repr(u8)] #[serde(rename_all = "SCREAMING_SNAKE_CASE")] -/// See https://discord.com/developers/docs/resources/stage-instance#stage-instance-object-privacy-level +/// See pub enum StageInstancePrivacyLevel { /// deprecated, apparently Public = 1, diff --git a/src/types/entities/template.rs b/src/types/entities/template.rs index b6eb3e9..2f934c9 100644 --- a/src/types/entities/template.rs +++ b/src/types/entities/template.rs @@ -6,7 +6,7 @@ use crate::types::{ utils::Snowflake, }; -/// See https://docs.spacebar.chat/routes/#cmp--schemas-template +/// See #[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq)] #[cfg_attr(feature = "sqlx", derive(sqlx::FromRow))] pub struct GuildTemplate { diff --git a/src/types/entities/voice_state.rs b/src/types/entities/voice_state.rs index aafc07f..94d3d79 100644 --- a/src/types/entities/voice_state.rs +++ b/src/types/entities/voice_state.rs @@ -6,7 +6,7 @@ use crate::types::{ utils::Snowflake, }; -/// See https://docs.spacebar.chat/routes/#cmp--schemas-voicestate +/// See #[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq)] #[cfg_attr(feature = "sqlx", derive(sqlx::FromRow))] pub struct VoiceState { diff --git a/src/types/entities/webhook.rs b/src/types/entities/webhook.rs index 521b93f..f953149 100644 --- a/src/types/entities/webhook.rs +++ b/src/types/entities/webhook.rs @@ -5,7 +5,7 @@ use crate::types::{ utils::Snowflake, }; -/// See https://docs.spacebar.chat/routes/#cmp--schemas-webhook +/// See #[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq)] #[cfg_attr(feature = "sqlx", derive(sqlx::FromRow))] pub struct Webhook { diff --git a/src/types/events/application.rs b/src/types/events/application.rs index 8afb374..7fee577 100644 --- a/src/types/events/application.rs +++ b/src/types/events/application.rs @@ -3,7 +3,7 @@ use serde::{Deserialize, Serialize}; use crate::types::{GuildApplicationCommandPermissions, WebSocketEvent}; #[derive(Debug, Deserialize, Serialize, Default, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#application-command-permissions-update +/// See pub struct ApplicationCommandPermissionsUpdate { #[serde(flatten)] pub permissions: GuildApplicationCommandPermissions, diff --git a/src/types/events/auto_moderation.rs b/src/types/events/auto_moderation.rs index d82aa02..0a1600b 100644 --- a/src/types/events/auto_moderation.rs +++ b/src/types/events/auto_moderation.rs @@ -6,7 +6,7 @@ use crate::types::{ }; #[derive(Debug, Deserialize, Serialize, Default, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#auto-moderation-rule-create +/// See pub struct AutoModerationRuleCreate { #[serde(flatten)] pub rule: AutoModerationRule, @@ -15,7 +15,7 @@ pub struct AutoModerationRuleCreate { impl WebSocketEvent for AutoModerationRuleCreate {} #[derive(Debug, Deserialize, Serialize, Default, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#auto-moderation-rule-update +/// See pub struct AutoModerationRuleUpdate { #[serde(flatten)] pub rule: AutoModerationRule, @@ -24,7 +24,7 @@ pub struct AutoModerationRuleUpdate { impl WebSocketEvent for AutoModerationRuleUpdate {} #[derive(Debug, Deserialize, Serialize, Default, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#auto-moderation-rule-delete +/// See pub struct AutoModerationRuleDelete { #[serde(flatten)] pub rule: AutoModerationRule, @@ -33,7 +33,7 @@ pub struct AutoModerationRuleDelete { impl WebSocketEvent for AutoModerationRuleDelete {} #[derive(Debug, Deserialize, Serialize, Default, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#auto-moderation-action-execution +/// See pub struct AutoModerationActionExecution { pub guild_id: Snowflake, pub action: AutoModerationAction, diff --git a/src/types/events/call.rs b/src/types/events/call.rs index 67225fb..e37c19d 100644 --- a/src/types/events/call.rs +++ b/src/types/events/call.rs @@ -50,7 +50,7 @@ impl WebSocketEvent for CallDelete {} #[derive(Debug, Deserialize, Serialize, Default, Clone)] /// Officially Undocumented; -/// See https://unofficial-discord-docs.vercel.app/gateway/op13; +/// See ; /// /// Ex: {"op":13,"d":{"channel_id":"837609115475771392"}} pub struct CallSync { diff --git a/src/types/events/channel.rs b/src/types/events/channel.rs index 99c7640..488bc47 100644 --- a/src/types/events/channel.rs +++ b/src/types/events/channel.rs @@ -4,7 +4,7 @@ use chrono::{DateTime, Utc}; use serde::{Deserialize, Serialize}; #[derive(Debug, Default, Deserialize, Serialize)] -/// See https://discord.com/developers/docs/topics/gateway-events#channel-pins-update +/// See pub struct ChannelPinsUpdate { pub guild_id: Option, pub channel_id: Snowflake, @@ -14,7 +14,7 @@ pub struct ChannelPinsUpdate { impl WebSocketEvent for ChannelPinsUpdate {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#channel-create +/// See pub struct ChannelCreate { #[serde(flatten)] pub channel: Channel, @@ -23,7 +23,7 @@ pub struct ChannelCreate { impl WebSocketEvent for ChannelCreate {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#channel-update +/// See pub struct ChannelUpdate { #[serde(flatten)] pub channel: Channel, @@ -42,7 +42,7 @@ pub struct ChannelUnreadUpdate { #[derive(Debug, Default, Deserialize, Serialize, Clone)] /// Contains very few fields from [Channel] -/// See also [ChannelUnreadUpdates] +/// See also [ChannelUnreadUpdate] pub struct ChannelUnreadUpdateObject { pub id: Snowflake, pub last_message_id: Snowflake, @@ -52,7 +52,7 @@ pub struct ChannelUnreadUpdateObject { impl WebSocketEvent for ChannelUnreadUpdate {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#channel-delete +/// See pub struct ChannelDelete { #[serde(flatten)] pub channel: Channel, diff --git a/src/types/events/guild.rs b/src/types/events/guild.rs index ae69681..2cbdbd0 100644 --- a/src/types/events/guild.rs +++ b/src/types/events/guild.rs @@ -10,7 +10,7 @@ use crate::types::{ use super::PresenceUpdate; #[derive(Debug, Deserialize, Serialize, Default, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#guild-create; +/// See ; /// Received to give data about a guild; // This one is particularly painful, it can be a Guild object with an extra field or an unavailable guild object pub struct GuildCreate { @@ -34,7 +34,7 @@ impl Default for GuildCreateDataOption { impl WebSocketEvent for GuildCreate {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#guild-ban-add-guild-ban-add-event-fields; +/// See ; /// Received to give info about a user being banned from a guild; pub struct GuildBanAdd { pub guild_id: Snowflake, @@ -44,7 +44,7 @@ pub struct GuildBanAdd { impl WebSocketEvent for GuildBanAdd {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#guild-ban-remove; +/// See ; /// Received to give info about a user being unbanned from a guild; pub struct GuildBanRemove { pub guild_id: Snowflake, @@ -54,7 +54,7 @@ pub struct GuildBanRemove { impl WebSocketEvent for GuildBanRemove {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#guild-update; +/// See ; /// Received to give info about a guild being updated; pub struct GuildUpdate { #[serde(flatten)] @@ -64,7 +64,7 @@ pub struct GuildUpdate { impl WebSocketEvent for GuildUpdate {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#guild-delete; +/// See ; /// Received to tell the client about a guild being deleted; pub struct GuildDelete { #[serde(flatten)] @@ -74,7 +74,7 @@ pub struct GuildDelete { impl WebSocketEvent for GuildDelete {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#guild-audit-log-entry-create; +/// See ; /// Received to the client about an audit log entry being added; pub struct GuildAuditLogEntryCreate { #[serde(flatten)] @@ -84,7 +84,7 @@ pub struct GuildAuditLogEntryCreate { impl WebSocketEvent for GuildAuditLogEntryCreate {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#guild-emojis-update; +/// See ; /// Received to tell the client about a change to a guild's emoji list; pub struct GuildEmojisUpdate { pub guild_id: Snowflake, @@ -94,7 +94,7 @@ pub struct GuildEmojisUpdate { impl WebSocketEvent for GuildEmojisUpdate {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#guild-stickers-update; +/// See ; /// Received to tell the client about a change to a guild's sticker list; pub struct GuildStickersUpdate { pub guild_id: Snowflake, @@ -104,7 +104,7 @@ pub struct GuildStickersUpdate { impl WebSocketEvent for GuildStickersUpdate {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#guild-integrations-update +/// See pub struct GuildIntegrationsUpdate { pub guild_id: Snowflake, } @@ -112,7 +112,7 @@ pub struct GuildIntegrationsUpdate { impl WebSocketEvent for GuildIntegrationsUpdate {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#guild-member-add; +/// See ; /// Received to tell the client about a user joining a guild; pub struct GuildMemberAdd { #[serde(flatten)] @@ -123,7 +123,7 @@ pub struct GuildMemberAdd { impl WebSocketEvent for GuildMemberAdd {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#guild-member-remove; +/// See ; /// Received to tell the client about a user leaving a guild; pub struct GuildMemberRemove { pub guild_id: Snowflake, @@ -133,7 +133,7 @@ pub struct GuildMemberRemove { impl WebSocketEvent for GuildMemberRemove {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#guild-member-update +/// See pub struct GuildMemberUpdate { pub guild_id: Snowflake, pub roles: Vec, @@ -151,7 +151,7 @@ pub struct GuildMemberUpdate { impl WebSocketEvent for GuildMemberUpdate {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#guild-members-chunk +/// See pub struct GuildMembersChunk { pub guild_id: Snowflake, pub members: Vec, @@ -165,7 +165,7 @@ pub struct GuildMembersChunk { impl WebSocketEvent for GuildMembersChunk {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#guild-role-create +/// See pub struct GuildRoleCreate { pub guild_id: Snowflake, pub role: RoleObject, @@ -174,7 +174,7 @@ pub struct GuildRoleCreate { impl WebSocketEvent for GuildRoleCreate {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#guild-role-update +/// See pub struct GuildRoleUpdate { pub guild_id: Snowflake, pub role: RoleObject, @@ -183,7 +183,7 @@ pub struct GuildRoleUpdate { impl WebSocketEvent for GuildRoleUpdate {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#guild-role-delete +/// See pub struct GuildRoleDelete { pub guild_id: Snowflake, pub role_id: Snowflake, @@ -192,7 +192,7 @@ pub struct GuildRoleDelete { impl WebSocketEvent for GuildRoleDelete {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#guild-scheduled-event-create +/// See pub struct GuildScheduledEventCreate { #[serde(flatten)] pub event: GuildScheduledEvent, @@ -201,7 +201,7 @@ pub struct GuildScheduledEventCreate { impl WebSocketEvent for GuildScheduledEventCreate {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#guild-scheduled-event-update +/// See pub struct GuildScheduledEventUpdate { #[serde(flatten)] pub event: GuildScheduledEvent, @@ -210,7 +210,7 @@ pub struct GuildScheduledEventUpdate { impl WebSocketEvent for GuildScheduledEventUpdate {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#guild-scheduled-event-delete +/// See pub struct GuildScheduledEventDelete { #[serde(flatten)] pub event: GuildScheduledEvent, @@ -219,7 +219,7 @@ pub struct GuildScheduledEventDelete { impl WebSocketEvent for GuildScheduledEventDelete {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#guild-scheduled-event-user-add +/// See pub struct GuildScheduledEventUserAdd { pub guild_scheduled_event_id: Snowflake, pub user_id: Snowflake, @@ -229,7 +229,7 @@ pub struct GuildScheduledEventUserAdd { impl WebSocketEvent for GuildScheduledEventUserAdd {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#guild-scheduled-event-user-remove +/// See pub struct GuildScheduledEventUserRemove { pub guild_scheduled_event_id: Snowflake, pub user_id: Snowflake, diff --git a/src/types/events/integration.rs b/src/types/events/integration.rs index de55a5b..2423e78 100644 --- a/src/types/events/integration.rs +++ b/src/types/events/integration.rs @@ -3,7 +3,7 @@ use serde::{Deserialize, Serialize}; use crate::types::{Integration, Snowflake, WebSocketEvent}; #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#integration-create +/// See pub struct IntegrationCreate { #[serde(flatten)] pub integration: Integration, @@ -13,7 +13,7 @@ pub struct IntegrationCreate { impl WebSocketEvent for IntegrationCreate {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#integration-update +/// See pub struct IntegrationUpdate { #[serde(flatten)] pub integration: Integration, @@ -23,7 +23,7 @@ pub struct IntegrationUpdate { impl WebSocketEvent for IntegrationUpdate {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#integration-delete +/// See pub struct IntegrationDelete { pub id: Snowflake, pub guild_id: Snowflake, diff --git a/src/types/events/interaction.rs b/src/types/events/interaction.rs index e77ee7c..304e7d4 100644 --- a/src/types/events/interaction.rs +++ b/src/types/events/interaction.rs @@ -3,7 +3,7 @@ use serde::{Deserialize, Serialize}; use crate::types::{Interaction, WebSocketEvent}; #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#interaction-create +/// See pub struct InteractionCreate { #[serde(flatten)] pub interaction: Interaction, diff --git a/src/types/events/invite.rs b/src/types/events/invite.rs index f04134d..674cc62 100644 --- a/src/types/events/invite.rs +++ b/src/types/events/invite.rs @@ -3,7 +3,7 @@ use serde::{Deserialize, Serialize}; use crate::types::{GuildInvite, Snowflake, WebSocketEvent}; #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#invite-create +/// See pub struct InviteCreate { #[serde(flatten)] pub invite: GuildInvite, @@ -12,7 +12,7 @@ pub struct InviteCreate { impl WebSocketEvent for InviteCreate {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#invite-delete +/// See pub struct InviteDelete { pub channel_id: Snowflake, pub guild_id: Option, diff --git a/src/types/events/lazy_request.rs b/src/types/events/lazy_request.rs index 2fd98af..fd53183 100644 --- a/src/types/events/lazy_request.rs +++ b/src/types/events/lazy_request.rs @@ -13,7 +13,7 @@ use super::WebSocketEvent; /// Sent by the official client when switching to a guild or channel; /// After this, you should recieve message updates /// -/// See https://luna.gitlab.io/discord-unofficial-docs/lazy_guilds.html#op-14-lazy-request +/// See /// /// {"op":14,"d":{"guild_id":"848582562217590824","typing":true,"activities":true,"threads":true}} pub struct LazyRequest { diff --git a/src/types/events/message.rs b/src/types/events/message.rs index 5a67417..70f28f6 100644 --- a/src/types/events/message.rs +++ b/src/types/events/message.rs @@ -19,7 +19,7 @@ pub struct TypingStartEvent { impl WebSocketEvent for TypingStartEvent {} #[derive(Debug, Serialize, Deserialize, Default, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#message-create +/// See pub struct MessageCreate { #[serde(flatten)] message: Message, @@ -29,7 +29,7 @@ pub struct MessageCreate { } #[derive(Debug, Serialize, Deserialize, Default, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#message-create-message-create-extra-fields +/// See pub struct MessageCreateUser { #[serde(flatten)] user: PublicUser, @@ -114,7 +114,7 @@ impl WebSocketEvent for MessageReactionRemoveEmoji {} /// /// Not documented anywhere unofficially /// -/// Apparently "Message ACK refers to marking a message as read for Discord's API." (https://github.com/Rapptz/discord.py/issues/1851) +/// Apparently "Message ACK refers to marking a message as read for Discord's API." () /// I suspect this is sent and recieved from the gateway to let clients on other devices know the user has read a message /// /// {"t":"MESSAGE_ACK","s":3,"op":0,"d":{"version":52,"message_id":"1107236673638633472","last_viewed":null,"flags":null,"channel_id":"967363950217936897"}} diff --git a/src/types/events/mod.rs b/src/types/events/mod.rs index 6333544..ed22a70 100644 --- a/src/types/events/mod.rs +++ b/src/types/events/mod.rs @@ -57,7 +57,7 @@ pub trait WebSocketEvent {} #[derive(Debug, Default, Serialize, Clone)] /// The payload used for sending events to the gateway /// -/// Similar to [GatewayReceivePayload], except we send a [Value] for d whilst we receive a [serde_json::value::RawValue] +/// Similar to [GatewayReceivePayload], except we send a [serde_json::value::Value] for d whilst we receive a [serde_json::value::RawValue] /// Also, we never need to send the event name pub struct GatewaySendPayload { #[serde(rename = "op")] @@ -76,9 +76,6 @@ impl WebSocketEvent for GatewaySendPayload {} #[derive(Debug, Default, Deserialize, Clone)] /// The payload used for receiving events from the gateway -/// -/// Similar to [GatewaySendPayload], except we send a [Value] for d whilst we receive a [serde_json::value::RawValue] -/// Also, we never need to sent the event name pub struct GatewayReceivePayload<'a> { #[serde(rename = "op")] pub op_code: u8, diff --git a/src/types/events/presence.rs b/src/types/events/presence.rs index ad06954..0aef27e 100644 --- a/src/types/events/presence.rs +++ b/src/types/events/presence.rs @@ -4,7 +4,7 @@ use serde::{Deserialize, Serialize}; #[derive(Debug, Deserialize, Serialize, Default, Clone)] /// Sent by the client to update its status and presence; -/// See https://discord.com/developers/docs/topics/gateway-events#update-presence +/// See pub struct UpdatePresence { /// unix time of when the client went idle, or none if client is not idle pub since: Option, @@ -16,7 +16,7 @@ pub struct UpdatePresence { #[derive(Debug, Deserialize, Serialize, Default, Clone)] /// Received to tell the client that a user updated their presence / status -/// See https://discord.com/developers/docs/topics/gateway-events#presence-update-presence-update-event-fields +/// See pub struct PresenceUpdate { pub user: PublicUser, #[serde(default)] diff --git a/src/types/events/ready.rs b/src/types/events/ready.rs index 9b6eab9..ea46b69 100644 --- a/src/types/events/ready.rs +++ b/src/types/events/ready.rs @@ -8,7 +8,7 @@ use crate::types::{Activity, GuildMember, PresenceUpdate, VoiceState}; #[derive(Debug, Deserialize, Serialize, Default, Clone)] /// 1/2 half documented; /// Received after identifying, provides initial user info; -/// See https://discord.com/developers/docs/topics/gateway-events#ready; +/// See pub struct GatewayReady { pub analytics_token: Option, pub auth_session_id_hash: Option, @@ -16,7 +16,7 @@ pub struct GatewayReady { pub v: u8, pub user: User, - /// For bots these are [UnavailableGuild]s, for users they are [Guild] + /// For bots these are [crate::types::UnavailableGuild]s, for users they are [Guild] pub guilds: Vec, pub presences: Option>, pub sessions: Option>, diff --git a/src/types/events/relationship.rs b/src/types/events/relationship.rs index 441c74a..a1f75a5 100644 --- a/src/types/events/relationship.rs +++ b/src/types/events/relationship.rs @@ -2,7 +2,7 @@ use crate::types::{events::WebSocketEvent, Relationship, RelationshipType, Snowf use serde::{Deserialize, Serialize}; #[derive(Debug, Deserialize, Serialize, Default)] -/// See https://github.com/spacebarchat/server/issues/204 +/// See pub struct RelationshipAdd { #[serde(flatten)] pub relationship: Relationship, @@ -12,7 +12,7 @@ pub struct RelationshipAdd { impl WebSocketEvent for RelationshipAdd {} #[derive(Debug, Deserialize, Serialize, Default, Clone)] -/// See https://github.com/spacebarchat/server/issues/203 +/// See pub struct RelationshipRemove { pub id: Snowflake, #[serde(rename = "type")] diff --git a/src/types/events/request_members.rs b/src/types/events/request_members.rs index 2d537b9..526313b 100644 --- a/src/types/events/request_members.rs +++ b/src/types/events/request_members.rs @@ -2,7 +2,7 @@ use crate::types::{events::WebSocketEvent, Snowflake}; use serde::{Deserialize, Serialize}; #[derive(Debug, Deserialize, Serialize, Default)] -/// See https://discord.com/developers/docs/topics/gateway-events#request-guild-members-request-guild-members-structure +/// See pub struct GatewayRequestGuildMembers { pub guild_id: Snowflake, pub query: Option, diff --git a/src/types/events/stage_instance.rs b/src/types/events/stage_instance.rs index 0fe487b..c2bbc46 100644 --- a/src/types/events/stage_instance.rs +++ b/src/types/events/stage_instance.rs @@ -3,7 +3,7 @@ use serde::{Deserialize, Serialize}; use crate::types::{StageInstance, WebSocketEvent}; #[derive(Debug, Deserialize, Serialize, Default, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#stage-instance-create +/// See pub struct StageInstanceCreate { #[serde(flatten)] pub stage_instance: StageInstance, @@ -12,7 +12,7 @@ pub struct StageInstanceCreate { impl WebSocketEvent for StageInstanceCreate {} #[derive(Debug, Deserialize, Serialize, Default, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#stage-instance-update +/// See pub struct StageInstanceUpdate { #[serde(flatten)] pub stage_instance: StageInstance, @@ -21,7 +21,7 @@ pub struct StageInstanceUpdate { impl WebSocketEvent for StageInstanceUpdate {} #[derive(Debug, Deserialize, Serialize, Default, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#stage-instance-delete +/// See pub struct StageInstanceDelete { #[serde(flatten)] pub stage_instance: StageInstance, diff --git a/src/types/events/thread.rs b/src/types/events/thread.rs index e8276e7..2faecf7 100644 --- a/src/types/events/thread.rs +++ b/src/types/events/thread.rs @@ -5,7 +5,7 @@ use crate::types::events::WebSocketEvent; use crate::types::Snowflake; #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#thread-create +/// See pub struct ThreadCreate { #[serde(flatten)] pub thread: Channel, @@ -14,7 +14,7 @@ pub struct ThreadCreate { impl WebSocketEvent for ThreadCreate {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#thread-update +/// See pub struct ThreadUpdate { #[serde(flatten)] pub thread: Channel, @@ -23,7 +23,7 @@ pub struct ThreadUpdate { impl WebSocketEvent for ThreadUpdate {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#thread-delete +/// See pub struct ThreadDelete { #[serde(flatten)] pub thread: Channel, @@ -32,7 +32,7 @@ pub struct ThreadDelete { impl WebSocketEvent for ThreadDelete {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#thread-list-sync +/// See pub struct ThreadListSync { pub guild_id: Snowflake, pub channel_ids: Option>, @@ -43,7 +43,7 @@ pub struct ThreadListSync { impl WebSocketEvent for ThreadListSync {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#thread-member-update +/// See /// The inner payload is a thread member object with an extra field. pub struct ThreadMemberUpdate { #[serde(flatten)] @@ -54,7 +54,7 @@ pub struct ThreadMemberUpdate { impl WebSocketEvent for ThreadMemberUpdate {} #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#thread-members-update +/// See pub struct ThreadMembersUpdate { pub id: Snowflake, pub guild_id: Snowflake, diff --git a/src/types/events/user.rs b/src/types/events/user.rs index 18c8511..e3ce99a 100644 --- a/src/types/events/user.rs +++ b/src/types/events/user.rs @@ -5,7 +5,7 @@ use crate::types::events::WebSocketEvent; use crate::types::utils::Snowflake; #[derive(Debug, Default, Deserialize, Serialize, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#user-update; +/// See ; /// Sent to indicate updates to a user object; (name changes, discriminator changes, etc); pub struct UserUpdate { #[serde(flatten)] diff --git a/src/types/events/voice.rs b/src/types/events/voice.rs index 63e740a..ff13b73 100644 --- a/src/types/events/voice.rs +++ b/src/types/events/voice.rs @@ -16,7 +16,7 @@ pub struct UpdateVoiceState { impl WebSocketEvent for UpdateVoiceState {} #[derive(Debug, Deserialize, Serialize, Default, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#voice-state-update; +/// See ; /// /// Received from the server to indicate an update in a user's voice state (leave voice channel, join voice channel, mute, deafen, etc); /// @@ -29,7 +29,7 @@ pub struct VoiceStateUpdate { impl WebSocketEvent for VoiceStateUpdate {} #[derive(Debug, Deserialize, Serialize, Default, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#voice-server-update; +/// See ; /// /// Received to indicate which voice endpoint, token and guild_id to use; pub struct VoiceServerUpdate { diff --git a/src/types/events/webhooks.rs b/src/types/events/webhooks.rs index 3f0158e..518b332 100644 --- a/src/types/events/webhooks.rs +++ b/src/types/events/webhooks.rs @@ -5,7 +5,7 @@ use crate::types::Snowflake; use super::WebSocketEvent; #[derive(Debug, Deserialize, Serialize, Default, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#webhooks-update +/// See pub struct WebhooksUpdate { pub guild_id: Snowflake, pub channel_id: Snowflake, diff --git a/src/types/interfaces/status.rs b/src/types/interfaces/status.rs index c82e665..fadaf68 100644 --- a/src/types/interfaces/status.rs +++ b/src/types/interfaces/status.rs @@ -1,7 +1,7 @@ use serde::{Deserialize, Serialize}; #[derive(Debug, Deserialize, Serialize, Default, Clone)] -/// See https://discord.com/developers/docs/topics/gateway-events#client-status-object +/// See pub struct ClientStatusObject { pub desktop: Option, pub mobile: Option, diff --git a/src/types/utils/snowflake.rs b/src/types/utils/snowflake.rs index 6176ea5..3a054b3 100644 --- a/src/types/utils/snowflake.rs +++ b/src/types/utils/snowflake.rs @@ -11,7 +11,7 @@ use sqlx::Type; const EPOCH: i64 = 1420070400000; /// Unique identifier including a timestamp. -/// See https://discord.com/developers/docs/reference#snowflakes +/// See #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)] #[cfg_attr(feature = "sqlx", derive(Type))] #[cfg_attr(feature = "sqlx", sqlx(transparent))] From d3613702bbd6a34f9babf91ef8e05dfe3319816b Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Tue, 11 Jul 2023 19:54:04 +0200 Subject: [PATCH 04/26] Add some docs --- src/api/auth/login.rs | 1 + src/api/auth/register.rs | 10 +--------- src/api/channels/channels.rs | 32 +++++--------------------------- 3 files changed, 7 insertions(+), 36 deletions(-) diff --git a/src/api/auth/login.rs b/src/api/auth/login.rs index baae4ae..1109fb8 100644 --- a/src/api/auth/login.rs +++ b/src/api/auth/login.rs @@ -11,6 +11,7 @@ use crate::ratelimiter::ChorusRequest; use crate::types::{LoginResult, LoginSchema}; impl Instance { + /// Logs into an existing account on the spacebar server. pub async fn login_account(&mut self, login_schema: &LoginSchema) -> ChorusResult { let endpoint_url = self.urls.api.clone() + "/auth/login"; let chorus_request = ChorusRequest { diff --git a/src/api/auth/register.rs b/src/api/auth/register.rs index e7b9d48..fa3d6c9 100644 --- a/src/api/auth/register.rs +++ b/src/api/auth/register.rs @@ -12,15 +12,7 @@ use crate::{ }; impl Instance { - /// Registers a new user on the Spacebar server. - /// - /// # Arguments - /// - /// * `register_schema` - The [`RegisterSchema`] that contains all the information that is needed to register a new user. - /// - /// # Errors - /// - /// * [`crate::errors::ChorusError`] - If the server does not respond. + /// Registers a new user on the server. pub async fn register_account( &mut self, register_schema: &RegisterSchema, diff --git a/src/api/channels/channels.rs b/src/api/channels/channels.rs index 82662e3..9cb65a9 100644 --- a/src/api/channels/channels.rs +++ b/src/api/channels/channels.rs @@ -10,6 +10,7 @@ use crate::{ }; impl Channel { + /// Retrieves a channel from the server. pub async fn get(user: &mut UserMeta, channel_id: Snowflake) -> ChorusResult { let url = user.belongs_to.borrow().urls.api.clone(); let chorus_request = ChorusRequest { @@ -21,19 +22,7 @@ impl Channel { chorus_request.deserialize_response::(user).await } - /// Deletes a channel. - /// - /// # Arguments - /// - /// * `token` - A string slice that holds the authorization token. - /// * `url_api` - A string slice that holds the URL of the API. - /// * `channel` - A `Channel` object that represents the channel to be deleted. - /// * `limits_user` - A mutable reference to a `Limits` object that represents the user's rate limits. - /// * `limits_instance` - A mutable reference to a `Limits` object that represents the instance's rate limits. - /// - /// # Returns - /// - /// A `Result` that contains a `ChorusLibError` if an error occurred during the request, or `()` if the request was successful. + /// Deletes self. pub async fn delete(self, user: &mut UserMeta) -> ChorusResult<()> { let chorus_request = ChorusRequest { request: Client::new() @@ -48,20 +37,8 @@ impl Channel { chorus_request.handle_request_as_result(user).await } - /// Modifies a channel. - /// - /// # Arguments - /// - /// * `modify_data` - A `ChannelModifySchema` object that represents the modifications to be made to the channel. - /// * `token` - A string slice that holds the authorization token. - /// * `url_api` - A string slice that holds the URL of the API. - /// * `channel_id` - A string slice that holds the ID of the channel to be modified. - /// * `limits_user` - A mutable reference to a `Limits` object that represents the user's rate limits. - /// * `limits_instance` - A mutable reference to a `Limits` object that represents the instance's rate limits. - /// - /// # Returns - /// - /// A `Result` that contains a `Channel` object if the request was successful, or an `ChorusLibError` if an error occurred during the request. + /// Modifies a channel with the provided data. + /// Replaces self with the new channel object. pub async fn modify( &mut self, modify_data: ChannelModifySchema, @@ -84,6 +61,7 @@ impl Channel { Ok(()) } + /// Fetches recent messages from a channel. pub async fn messages( range: GetChannelMessagesSchema, channel_id: Snowflake, From 1f9efa98e3bf4e79eac9e042aacaf55407765a93 Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Fri, 28 Jul 2023 18:45:40 +0200 Subject: [PATCH 05/26] Better docs --- src/api/channels/channels.rs | 2 +- src/api/channels/messages.rs | 8 +-- src/api/channels/permissions.rs | 20 ------- src/api/channels/reactions.rs | 92 ++++++++++++++------------------- src/api/guilds/guilds.rs | 71 ++++--------------------- 5 files changed, 55 insertions(+), 138 deletions(-) diff --git a/src/api/channels/channels.rs b/src/api/channels/channels.rs index a8bc7ee..db94056 100644 --- a/src/api/channels/channels.rs +++ b/src/api/channels/channels.rs @@ -39,7 +39,7 @@ impl Channel { } /// Modifies a channel with the provided data. - /// Replaces self with the new channel object. + /// Returns the new Channel. pub async fn modify( &self, modify_data: ChannelModifySchema, diff --git a/src/api/channels/messages.rs b/src/api/channels/messages.rs index 63ebebc..9c06f6f 100644 --- a/src/api/channels/messages.rs +++ b/src/api/channels/messages.rs @@ -10,7 +10,8 @@ use crate::ratelimiter::ChorusRequest; use crate::types::{Message, MessageSendSchema, Snowflake}; impl Message { - /// Sends a message to the Spacebar server. + /// Sends a message in the channel with the provided channel_id. + /// Returns the sent message. pub async fn send( user: &mut UserMeta, channel_id: Snowflake, @@ -68,14 +69,15 @@ impl Message { } impl UserMeta { - /// Sends a message to the Spacebar server. + /// Sends a message in the channel with the provided channel_id. + /// Returns the sent message. /// # Notes /// Shorthand call for Message::send() pub async fn send_message( &mut self, message: MessageSendSchema, channel_id: Snowflake, - ) -> ChorusResult { + ) -> ChorusResult { Message::send(self, channel_id, message).await } } diff --git a/src/api/channels/permissions.rs b/src/api/channels/permissions.rs index bc666ff..57feb5d 100644 --- a/src/api/channels/permissions.rs +++ b/src/api/channels/permissions.rs @@ -11,16 +11,6 @@ use crate::{ impl types::Channel { /// Edits the permission overwrites for a channel. - /// - /// # Arguments - /// - /// * `user` - A mutable reference to a [`UserMeta`] instance. - /// * `channel_id` - A string slice representing the ID of the channel. - /// * `overwrite` - A [`PermissionOverwrite`] instance representing the new permission overwrites. - /// - /// # Returns - /// - /// This function returns a result that is either [`Ok(())`] if the request is successful, or an [`Err(ChorusLibError)`]. pub async fn edit_permissions( user: &mut UserMeta, channel_id: Snowflake, @@ -48,16 +38,6 @@ impl types::Channel { } /// Deletes a permission overwrite for a channel. - /// - /// # Arguments - /// - /// * `user` - A mutable reference to a [`UserMeta`] instance. - /// * `channel_id` - A string slice representing the ID of the channel. - /// * `overwrite_id` - A string slice representing the ID of the permission overwrite to delete. - /// - /// # Returns - /// - /// This function returns a Result that is either [`Ok(())`] if the request is successfulm or an [`Err(ChorusLibError)`]. pub async fn delete_permission( user: &mut UserMeta, channel_id: Snowflake, diff --git a/src/api/channels/reactions.rs b/src/api/channels/reactions.rs index fe1e57f..467af56 100644 --- a/src/api/channels/reactions.rs +++ b/src/api/channels/reactions.rs @@ -16,12 +16,11 @@ 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. - /// # Arguments - /// * `user` - A mutable reference to a [`UserMeta`] instance. - /// # Returns - /// A `Result` [`()`] [`crate::errors::ChorusError`] if something went wrong. + /// /// Fires a `Message Reaction Remove All` Gateway event. + /// /// # Reference /// See pub async fn delete_all(&self, user: &mut UserMeta) -> ChorusResult<()> { @@ -39,13 +38,10 @@ impl ReactionMeta { } /// Gets a list of users that reacted with a specific emoji to a message. - /// # Arguments - /// * `emoji` - A string slice containing the emoji to search for. The emoji must be URL Encoded or - /// the request will fail with 10014: Unknown Emoji. To use custom emoji, you must encode it in the - /// format name:id with the emoji name and emoji id. - /// * `user` - A mutable reference to a [`UserMeta`] instance. - /// # Returns - /// A Result that is [`Err(crate::errors::ChorusLibError)`] if something went wrong. + /// + /// 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. + /// /// # Reference /// See pub async fn get(&self, emoji: &str, user: &mut UserMeta) -> ChorusResult> { @@ -65,16 +61,15 @@ impl ReactionMeta { .await } - /// Deletes all the reactions for a given `emoji` on a message. This endpoint requires the - /// MANAGE_MESSAGES permission to be present on the current user. - /// # Arguments - /// * `emoji` - A string slice containing the emoji to delete. The `emoji` must be URL Encoded or - /// the request will fail with 10014: Unknown Emoji. To use custom emoji, you must encode it in the - /// format name:id with the emoji name and emoji id. - /// * `user` - A mutable reference to a [`UserMeta`] instance. - /// # Returns - /// A Result that is [`Err(crate::errors::ChorusLibError)`] if something went wrong. - /// Fires a `Message Reaction Remove Emoji` Gateway event. + /// Deletes all the reactions for a given emoji on a message. + /// + /// This endpoint requires the 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<()> { @@ -92,21 +87,18 @@ impl ReactionMeta { chorus_request.handle_request_as_result(user).await } - /// Create a reaction for the message. - /// This endpoint requires the READ_MESSAGE_HISTORY permission - /// to be present on the current user. Additionally, if nobody else has reacted to the message using - /// this emoji, this endpoint requires the ADD_REACTIONS permission to be present on the current - /// user. - /// # Arguments - /// * `emoji` - A string slice containing the emoji to delete. The `emoji` must be URL Encoded or - /// the request will fail with 10014: Unknown Emoji. To use custom emoji, you must encode it in the - /// format name:id with the emoji name and emoji id. - /// * `user` - A mutable reference to a [`UserMeta`] instance. - /// # Returns - /// A `Result` containing [`()`] or a [`crate::errors::ChorusError`]. + /// Create a reaction on a message. + /// + /// This endpoint requires the READ_MESSAGE_HISTORY permission. + /// + /// Additionally, if nobody else has reacted to the message using this emoji, + /// this endpoint requires the 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. + /// /// # Reference /// See - /// pub async fn create(&self, emoji: &str, user: &mut UserMeta) -> ChorusResult<()> { let url = format!( "{}/channels/{}/messages/{}/reactions/{}/@me/", @@ -122,15 +114,13 @@ impl ReactionMeta { chorus_request.handle_request_as_result(user).await } - /// Delete a reaction the current user has made for the message. - /// # Arguments - /// * `emoji` - A string slice containing the emoji to delete. The `emoji` must be URL Encoded or - /// the request will fail with 10014: Unknown Emoji. To use custom emoji, you must encode it in the - /// format name:id with the emoji name and emoji id. - /// * `user` - A mutable reference to a [`UserMeta`] instance. - /// # Returns - /// A `Result` containing [`()`] or a [`crate::errors::ChorusError`]. + /// Deletes a reaction the current user has made to the message. + /// + /// 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<()> { @@ -148,17 +138,15 @@ impl ReactionMeta { chorus_request.handle_request_as_result(user).await } - /// Delete a user's reaction to a message. - /// This endpoint requires the MANAGE_MESSAGES permission to be present on the current user. - /// # Arguments - /// * `user_id` - ID of the user whose reaction is to be deleted. - /// * `emoji` - A string slice containing the emoji to delete. The `emoji` must be URL Encoded or - /// the request will fail with 10014: Unknown Emoji. To use custom emoji, you must encode it in the - /// format name:id with the emoji name and emoji id. - /// * `user` - A mutable reference to a [`UserMeta`] instance. - /// # Returns - /// A [`ChorusResult`] containing [`()`] or a [`crate::errors::ChorusError`]. + /// Deletes a user's reaction to a message. + /// + /// This endpoint requires the 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 3654698..d4abcab 100644 --- a/src/api/guilds/guilds.rs +++ b/src/api/guilds/guilds.rs @@ -11,22 +11,7 @@ use crate::types::Snowflake; use crate::types::{Channel, ChannelCreateSchema, Guild, GuildCreateSchema}; impl Guild { - /// Creates a new guild with the given parameters. - /// - /// # Arguments - /// - /// * `user` - A mutable reference to the user creating the guild. - /// * `instance` - A mutable reference to the instance where the guild will be created. - /// * `guild_create_schema` - A reference to the schema containing the guild creation parameters. - /// - /// # Returns - /// - /// A `Result` containing the object of the newly created guild, or an error if the request fails. - /// - /// # Errors - /// - /// Returns an `ChorusLibError` if the request fails. - /// + /// Creates a new guild. pub async fn create( user: &mut UserMeta, guild_create_schema: GuildCreateSchema, @@ -42,17 +27,7 @@ impl Guild { chorus_request.deserialize_response::(user).await } - /// Deletes a guild. - /// - /// # Arguments - /// - /// * `user` - A mutable reference to a `User` instance. - /// * `instance` - A mutable reference to an `Instance` instance. - /// * `guild_id` - ID of the guild to delete. - /// - /// # Returns - /// - /// An `Result` containing an `ChorusLibError` if an error occurred during the request, otherwise `()`. + /// Deletes a guild by its id. /// /// # Example /// @@ -61,9 +36,9 @@ impl Guild { /// let mut instance = Instance::new(); /// let guild_id = String::from("1234567890"); /// - /// match Guild::delete(&mut user, &mut instance, guild_id) { - /// Some(e) => println!("Error deleting guild: {:?}", e), - /// None => println!("Guild deleted successfully"), + /// match Guild::delete(&mut user, guild_id) { + /// Err(e) => println!("Error deleting guild: {:?}", e), + /// Ok(_) => println!("Guild deleted successfully"), /// } /// ``` pub async fn delete(user: &mut UserMeta, guild_id: Snowflake) -> ChorusResult<()> { @@ -81,19 +56,7 @@ impl Guild { chorus_request.handle_request_as_result(user).await } - /// Sends a request to create a new channel in the guild. - /// - /// # Arguments - /// - /// * `url_api` - The base URL for the Discord API. - /// * `token` - A Discord bot token. - /// * `schema` - A `ChannelCreateSchema` struct containing the properties of the new channel. - /// * `limits_user` - A mutable reference to a `Limits` struct containing the user's rate limits. - /// * `limits_instance` - A mutable reference to a `Limits` struct containing the instance's rate limits. - /// - /// # Returns - /// - /// A `Result` containing a `reqwest::Response` if the request was successful, or an `ChorusLibError` if there was an error. + /// Creates a new channel in a guild. pub async fn create_channel( &self, user: &mut UserMeta, @@ -102,15 +65,7 @@ impl Guild { Channel::create(user, self.id, schema).await } - /// Returns a `Result` containing a vector of `Channel` structs if the request was successful, or an `ChorusLibError` if there was an error. - /// - /// # Arguments - /// - /// * `url_api` - A string slice that holds the URL of the API. - /// * `token` - A string slice that holds the authorization token. - /// * `limits_user` - A mutable reference to a `Limits` struct containing the user's rate limits. - /// * `limits_instance` - A mutable reference to a `Limits` struct containing the instance's rate limits. - /// + // TODO: Docs: What is this endpoint? pub async fn channels(&self, user: &mut UserMeta) -> ChorusResult> { let chorus_request = ChorusRequest { request: Client::new() @@ -141,16 +96,8 @@ impl Guild { }; } - /// Returns a `Result` containing a `Guild` struct if the request was successful, or an `ChorusLibError` if there was an error. - /// - /// # Arguments - /// - /// * `url_api` - A string slice that holds the URL of the API. - /// * `guild_id` - ID of the guild. - /// * `token` - A string slice that holds the authorization token. - /// * `limits_user` - A mutable reference to a `Limits` struct containing the user's rate limits. - /// * `limits_instance` - A mutable reference to a `Limits` struct containing the instance's rate limits. - /// + // TODO: Check if these docs are correct, Im not sure what this endpoint is + /// Fetches a given guild. pub async fn get(guild_id: Snowflake, user: &mut UserMeta) -> ChorusResult { let chorus_request = ChorusRequest { request: Client::new() From a2ddafb6a1736a62851c44d7e53bc687a916a4e8 Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Fri, 28 Jul 2023 18:57:35 +0200 Subject: [PATCH 06/26] Remove the todos from the last commit --- src/api/guilds/guilds.rs | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/api/guilds/guilds.rs b/src/api/guilds/guilds.rs index d4abcab..97286d8 100644 --- a/src/api/guilds/guilds.rs +++ b/src/api/guilds/guilds.rs @@ -65,7 +65,7 @@ impl Guild { Channel::create(user, self.id, schema).await } - // TODO: Docs: What is this endpoint? + /// Returns a list of the guild's channels pub async fn channels(&self, user: &mut UserMeta) -> ChorusResult> { let chorus_request = ChorusRequest { request: Client::new() @@ -96,8 +96,7 @@ impl Guild { }; } - // TODO: Check if these docs are correct, Im not sure what this endpoint is - /// Fetches a given guild. + /// Fetches a guild by its id. pub async fn get(guild_id: Snowflake, user: &mut UserMeta) -> ChorusResult { let chorus_request = ChorusRequest { request: Client::new() From 787da3092c35a1ebde6d470a60b33631b596e6c3 Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Sat, 29 Jul 2023 10:23:04 +0200 Subject: [PATCH 07/26] Moar docs --- src/api/guilds/guilds.rs | 15 +------- src/api/guilds/member.rs | 34 +---------------- src/api/guilds/roles.rs | 54 ++------------------------- src/api/invites/mod.rs | 23 ++++++++++-- src/api/policies/instance/instance.rs | 2 - src/api/users/guilds.rs | 4 +- src/api/users/relationships.rs | 49 +++++++----------------- src/api/users/users.rs | 51 ++++++++----------------- src/instance.rs | 8 ++++ src/lib.rs | 13 ++++--- tests/invites.rs | 2 +- 11 files changed, 70 insertions(+), 185 deletions(-) diff --git a/src/api/guilds/guilds.rs b/src/api/guilds/guilds.rs index 97286d8..9b9d87f 100644 --- a/src/api/guilds/guilds.rs +++ b/src/api/guilds/guilds.rs @@ -114,20 +114,7 @@ impl Guild { } impl Channel { - /// Sends a request to create a new channel in a guild. - /// - /// # Arguments - /// - /// * `token` - A Discord bot token. - /// * `url_api` - The base URL for the Discord API. - /// * `guild_id` - The ID of the guild where the channel will be created. - /// * `schema` - A `ChannelCreateSchema` struct containing the properties of the new channel. - /// * `limits_user` - A mutable reference to a `Limits` struct containing the user's rate limits. - /// * `limits_instance` - A mutable reference to a `Limits` struct containing the instance's rate limits. - /// - /// # Returns - /// - /// A `Result` containing a `reqwest::Response` if the request was successful, or an `ChorusLibError` if there was an error. + /// Creates a new channel in a guild. pub async fn create( user: &mut UserMeta, guild_id: Snowflake, diff --git a/src/api/guilds/member.rs b/src/api/guilds/member.rs index c7e26b9..1cf1a08 100644 --- a/src/api/guilds/member.rs +++ b/src/api/guilds/member.rs @@ -9,17 +9,7 @@ use crate::{ }; impl types::GuildMember { - /// Retrieves a guild member by their ID. - /// - /// # Arguments - /// - /// * `user` - A mutable reference to a [`UserMeta`] instance. - /// * `guild_id` - The ID of the guild. - /// * `member_id` - The ID of the member. - /// - /// # Returns - /// - /// A [`ChorusResult`] containing a [`GuildMember`] if the request succeeds. + /// Retrieves a guild member. pub async fn get( user: &mut UserMeta, guild_id: Snowflake, @@ -41,17 +31,6 @@ impl types::GuildMember { } /// Adds a role to a guild member. - /// - /// # Arguments - /// - /// * `user` - A mutable reference to a `UserMeta` instance. - /// * `guild_id` - The ID of the guild. - /// * `member_id` - The ID of the member. - /// * `role_id` - The ID of the role to add. - /// - /// # Returns - /// - /// A [`ChorusResult`] containing a [`crate::errors::ChorusError`] if the request fails, or `()` if the request succeeds. pub async fn add_role( user: &mut UserMeta, guild_id: Snowflake, @@ -73,17 +52,6 @@ impl types::GuildMember { } /// Removes a role from a guild member. - /// - /// # Arguments - /// - /// * `user` - A mutable reference to a `UserMeta` instance. - /// * `guild_id` - The ID of the guild. - /// * `member_id` - The ID of the member. - /// * `role_id` - The ID of the role to remove. - /// - /// # Returns - /// - /// A [`ChorusResult`] containing a [`crate::errors::ChorusError`] if the request fails, or `()` if the request succeeds. pub async fn remove_role( user: &mut UserMeta, guild_id: Snowflake, diff --git a/src/api/guilds/roles.rs b/src/api/guilds/roles.rs index f8cade9..81aca03 100644 --- a/src/api/guilds/roles.rs +++ b/src/api/guilds/roles.rs @@ -10,16 +10,9 @@ use crate::{ }; impl types::RoleObject { - /// Retrieves all roles for a given guild. + /// Retrieves a list of roles for a given guild. /// - /// # Arguments - /// - /// * `user` - A mutable reference to a [`UserMeta`] instance. - /// * `guild_id` - The ID of the guild to retrieve roles from. - /// - /// # Returns - /// - /// An `Option` containing a `Vec` of [`RoleObject`]s if roles were found, or `None` if no roles were found. + /// Returns Ok(None) if the guild has no roles. pub async fn get_all( user: &mut UserMeta, guild_id: Snowflake, @@ -44,16 +37,6 @@ impl types::RoleObject { } /// Retrieves a single role for a given guild. - /// - /// # Arguments - /// - /// * `user` - A mutable reference to a [`UserMeta`] instance. - /// * `guild_id` - The ID of the guild to retrieve the role from. - /// * `role_id` - The ID of the role to retrieve. - /// - /// # Returns - /// - /// A `Result` containing the retrieved [`RoleObject`] if successful, or a [`ChorusError`] if the request fails or if the response is invalid. pub async fn get( user: &mut UserMeta, guild_id: Snowflake, @@ -75,16 +58,6 @@ impl types::RoleObject { } /// Creates a new role for a given guild. - /// - /// # Arguments - /// - /// * `user` - A mutable reference to a [`UserMeta`] instance. - /// * `guild_id` - The ID of the guild to create the role in. - /// * `role_create_schema` - A [`RoleCreateModifySchema`] instance containing the properties of the role to be created. - /// - /// # Returns - /// - /// A `Result` containing the newly created [`RoleObject`] if successful, or a [`ChorusError`] if the request fails or if the response is invalid. pub async fn create( user: &mut UserMeta, guild_id: Snowflake, @@ -109,17 +82,7 @@ impl types::RoleObject { .await } - /// Updates the position of a role in the guild's hierarchy. - /// - /// # Arguments - /// - /// * `user` - A mutable reference to a [`UserMeta`] instance. - /// * `guild_id` - The ID of the guild to update the role position in. - /// * `role_position_update_schema` - A [`RolePositionUpdateSchema`] instance containing the new position of the role. - /// - /// # Returns - /// - /// A `Result` containing the updated [`RoleObject`] if successful, or a [`ChorusError`] if the request fails or if the response is invalid. + /// Updates the position of a role in a given guild's hierarchy. pub async fn position_update( user: &mut UserMeta, guild_id: Snowflake, @@ -147,17 +110,6 @@ impl types::RoleObject { } /// Updates a role in a guild. - /// - /// # Arguments - /// - /// * `user` - A mutable reference to a [`UserMeta`] instance. - /// * `guild_id` - The ID of the guild to update the role in. - /// * `role_id` - The ID of the role to update. - /// * `role_create_schema` - A [`RoleCreateModifySchema`] instance containing the new properties of the role. - /// - /// # Returns - /// - /// A `Result` containing the updated [`RoleObject`] if successful, or a [`ChorusError`] if the request fails or if the response is invalid. pub async fn update( user: &mut UserMeta, guild_id: Snowflake, diff --git a/src/api/invites/mod.rs b/src/api/invites/mod.rs index b766a5b..343f44d 100644 --- a/src/api/invites/mod.rs +++ b/src/api/invites/mod.rs @@ -7,9 +7,11 @@ use crate::ratelimiter::ChorusRequest; use crate::types::{CreateChannelInviteSchema, GuildInvite, Invite, Snowflake}; impl UserMeta { - /// # Arguments - /// - invite_code: The invite code to accept the invite for. - /// - session_id: The session ID that is accepting the invite, required for guest invites. + /// Accepts an invite to a guild, group DM, or DM. + /// + /// 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 @@ -35,7 +37,13 @@ impl UserMeta { } request.deserialize_response::(self).await } + + /// Creates a new friend invite. + /// /// Note: Spacebar does not yet implement this endpoint. + /// + /// # Reference: + /// Read pub async fn create_user_invite(&mut self, code: Option<&str>) -> ChorusResult { ChorusRequest { request: Client::new() @@ -51,7 +59,14 @@ impl UserMeta { .await } - pub async fn create_guild_invite( + /// Creates a new invite for a guild channel or group DM. + /// + /// # Guild Channels + /// For guild channels, the endpoint + /// requires the CREATE_INSTANT_INVITE permission. + /// + /// Guild channel invites also fire an Invite Create Gateway event. + pub async fn create_channel_invite( &mut self, create_channel_invite_schema: CreateChannelInviteSchema, channel_id: Snowflake, diff --git a/src/api/policies/instance/instance.rs b/src/api/policies/instance/instance.rs index d015778..ae6e5d5 100644 --- a/src/api/policies/instance/instance.rs +++ b/src/api/policies/instance/instance.rs @@ -6,8 +6,6 @@ use crate::types::GeneralConfiguration; impl Instance { /// Gets the instance policies schema. - /// # Errors - /// [`ChorusError`] - If the request fails. 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/guilds.rs b/src/api/users/guilds.rs index 735ed9e..dd52507 100644 --- a/src/api/users/guilds.rs +++ b/src/api/users/guilds.rs @@ -7,11 +7,11 @@ use crate::ratelimiter::ChorusRequest; use crate::types::Snowflake; impl UserMeta { - /// # Arguments: - /// - lurking: Whether the user is lurking in the guild + /// Leaves a given guild. /// /// # Reference: /// Read + // TODO: Docs: What is lurking here? pub async fn leave_guild(&mut self, guild_id: &Snowflake, lurking: bool) -> ChorusResult<()> { ChorusRequest { request: Client::new() diff --git a/src/api/users/relationships.rs b/src/api/users/relationships.rs index a864706..a5afaac 100644 --- a/src/api/users/relationships.rs +++ b/src/api/users/relationships.rs @@ -12,14 +12,10 @@ use crate::{ }; impl UserMeta { - /// Retrieves the mutual relationships between the authenticated user and the specified user. + /// Retrieves a list of mutual friends between the authenticated user and a given user. /// - /// # Arguments - /// - /// * `user_id` - ID of the user to retrieve the mutual relationships with. - /// - /// # Returns - /// This function returns a [`ChorusResult>`]. + /// # Reference + /// See pub async fn get_mutual_relationships( &mut self, user_id: Snowflake, @@ -38,10 +34,10 @@ impl UserMeta { .await } - /// Retrieves the authenticated user's relationships. + /// Retrieves the user's relationships. /// - /// # Returns - /// This function returns a [`ChorusResult>`]. + /// # Reference + /// See pub async fn get_relationships(&mut self) -> ChorusResult> { let url = format!( "{}/users/@me/relationships/", @@ -58,12 +54,8 @@ impl UserMeta { /// Sends a friend request to a user. /// - /// # Arguments - /// - /// * `schema` - A [`FriendRequestSendSchema`] struct that holds the information about the friend request to be sent. - /// - /// # Returns - /// This function returns a [`ChorusResult`]. + /// # Reference + /// See pub async fn send_friend_request( &mut self, schema: FriendRequestSendSchema, @@ -80,20 +72,9 @@ impl UserMeta { chorus_request.handle_request_as_result(self).await } - /// Modifies the relationship between the authenticated user and the specified user. + /// Modifies the relationship between the authenticated user and a given user. /// - /// # Arguments - /// - /// * `user_id` - ID of the user to modify the relationship with. - /// * `relationship_type` - A [`RelationshipType`] enum that specifies the type of relationship to modify. - /// * [`RelationshipType::None`]: Removes the relationship between the two users. - /// * [`RelationshipType::Friends`] | [`RelationshipType::Incoming`] | [`RelationshipType::Outgoing`]: - /// Either accepts an incoming friend request, or sends a new friend request, if there is no - /// incoming friend request from the specified `user_id`. - /// * [`RelationshipType::Blocked`]: Blocks the specified user_id. - /// - /// # Returns - /// This function returns an [`ChorusResult`]. + /// Can be used to unfriend users, accept or send friend requests and block or unblock users. pub async fn modify_user_relationship( &mut self, user_id: Snowflake, @@ -144,14 +125,10 @@ impl UserMeta { } } - /// Removes the relationship between the authenticated user and the specified user. + /// Removes the relationship between the authenticated user and a given user. /// - /// # Arguments - /// - /// * `user_id` - ID of the user to remove the relationship with. - /// - /// # Returns - /// This function returns a [`ChorusResult`]. + /// # Reference + /// See pub async fn remove_relationship(&mut self, user_id: Snowflake) -> ChorusResult<()> { let url = format!( "{}/users/@me/relationships/{}/", diff --git a/src/api/users/users.rs b/src/api/users/users.rs index 9e7d2af..f673ee3 100644 --- a/src/api/users/users.rs +++ b/src/api/users/users.rs @@ -12,21 +12,18 @@ use crate::{ }; impl UserMeta { - /// Get a user object by id, or get the current user. + /// Gets a user by id, or if the id is None, gets the current user. /// - /// # Arguments - /// - /// * `token` - A valid access token for the API. - /// * `url_api` - The URL to the API. - /// * `id` - The id of the user that will be retrieved. If this is None, the current user will be retrieved. - /// - /// # Errors - /// - /// * [`ChorusError`] - If the request fails. + /// # Notes + /// This function is a wrapper around [`User::get`]. pub async fn get(user: &mut UserMeta, id: Option<&String>) -> ChorusResult { User::get(user, id).await } + /// Gets the user's settings. + /// + /// # Notes + /// This functions is a wrapper around [`User::get_settings`]. pub async fn get_settings( token: &String, url_api: &String, @@ -35,15 +32,7 @@ impl UserMeta { User::get_settings(token, url_api, instance).await } - /// Modify the current user's `UserObject`. - /// - /// # Arguments - /// - /// * `modify_schema` - A `UserModifySchema` object containing the fields to modify. - /// - /// # Errors - /// - /// Returns an [`ChorusError`] if the request fails or if a password is required but not provided. + /// Modifies the current user's representation. (See [`User`]) pub async fn modify(&mut self, modify_schema: UserModifySchema) -> ChorusResult { if modify_schema.new_password.is_some() || modify_schema.email.is_some() @@ -67,15 +56,7 @@ impl UserMeta { Ok(user_updated) } - /// Sends a request to the server which deletes the user from the Instance. - /// - /// # Arguments - /// - /// * `self` - The `User` object to delete. - /// - /// # Returns - /// - /// Returns `()` if the user was successfully deleted, or a [`ChorusError`] if an error occurred. + /// Deletes the user from the Instance. pub async fn delete(mut self) -> ChorusResult<()> { let request = Client::new() .post(format!( @@ -92,6 +73,7 @@ impl UserMeta { } impl User { + /// Gets a user by id, or if the id is None, gets the current user. pub async fn get(user: &mut UserMeta, id: Option<&String>) -> ChorusResult { let url_api = user.belongs_to.borrow().urls.api.clone(); let url = if id.is_none() { @@ -113,6 +95,7 @@ impl User { } } + /// Gets the user's settings. pub async fn get_settings( token: &String, url_api: &String, @@ -140,14 +123,10 @@ impl User { } impl Instance { - // Get a user object by id, or get the current user. - // # Arguments - // * `token` - A valid access token for the API. - // * `id` - The id of the user that will be retrieved. If this is None, the current user will be retrieved. - // # Errors - // * [`ChorusError`] - If the request fails. - // # Notes - // This function is a wrapper around [`User::get`]. + /// Gets a user by id, or if the id is None, gets the current user. + /// + /// # Notes + /// This function is a wrapper around [`User::get`]. pub async fn get_user(&mut self, token: String, id: Option<&String>) -> ChorusResult { let mut user = UserMeta::shell(Rc::new(RefCell::new(self.clone())), token).await; let result = User::get(&mut user, id).await; diff --git a/src/instance.rs b/src/instance.rs index 2360390..f034513 100644 --- a/src/instance.rs +++ b/src/instance.rs @@ -83,6 +83,9 @@ impl fmt::Display for Token { } #[derive(Debug)] +/// A UserMeta is a representation of an authenticated user on an [Instance]. +/// It is used for most authenticated actions on a Spacebar server. +/// It also has its own [Gateway] connection. pub struct UserMeta { pub belongs_to: Rc>, pub token: String, @@ -101,6 +104,11 @@ impl UserMeta { self.token = token; } + /// Creates a new [UserMeta] from existing data. + /// + /// # Notes + /// This isn't the prefered way to create a UserMeta. + /// See [Instance::login_account] and [Instance::register_account] instead. pub fn new( belongs_to: Rc>, token: String, diff --git a/src/lib.rs b/src/lib.rs index 5b14544..8315a4d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -16,8 +16,8 @@ pub mod types; pub mod voice; #[derive(Clone, Default, Debug, PartialEq, Eq)] -/// A URLBundle is a struct which bundles together the API-, Gateway- and CDN-URLs of a Spacebar -/// instance. +/// A URLBundle bundles together the API-, Gateway- and CDN-URLs of a Spacebar instance. +/// /// # Notes /// All the urls can be found on the /api/policies/instance/domains endpoint of a spacebar server pub struct UrlBundle { @@ -25,7 +25,7 @@ pub struct UrlBundle { /// Ex: `https://old.server.spacebar.chat/api` pub api: String, /// The gateway websocket url. - /// Note that because this is a websocket url, it will always start with `wss://` + /// Note that because this is a websocket url, it will always start with `wss://` or `ws://` /// Ex: `wss://gateway.old.server.spacebar.chat` pub wss: String, /// The CDN's url. @@ -42,9 +42,10 @@ impl UrlBundle { } } - /// parse(url: String) parses a URL using the Url library and formats it in a standardized - /// way. If no protocol is given, HTTP (not HTTPS) is assumed. - /// # Example: + /// Parses a URL using the Url library and formats it in a standardized way. + /// If no protocol is given, HTTP (not HTTPS) is assumed. + /// + /// # Examples: /// ```rs /// let url = parse_url("localhost:3000"); /// ``` diff --git a/tests/invites.rs b/tests/invites.rs index d19be61..e25fea5 100644 --- a/tests/invites.rs +++ b/tests/invites.rs @@ -11,7 +11,7 @@ async fn create_accept_invite() { .await .is_err()); let invite = user - .create_guild_invite(create_channel_invite_schema, channel.id) + .create_channel_invite(create_channel_invite_schema, channel.id) .await .unwrap(); From 3058025e9d4947b03dae3d11c56cec253779d14a Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Sat, 29 Jul 2023 11:00:28 +0200 Subject: [PATCH 08/26] Document rights --- src/types/utils/rights.rs | 74 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/src/types/utils/rights.rs b/src/types/utils/rights.rs index fecf268..dc4955a 100644 --- a/src/types/utils/rights.rs +++ b/src/types/utils/rights.rs @@ -1,56 +1,124 @@ use bitflags::bitflags; bitflags! { + /// Rights are instance-wide, per-user permissions for everything you may perform on the instance, + /// such as sending messages, editing messages, or shutting down the server. + /// They are separate from guild member permissions, which only apply to a given guild. + /// + /// # Notes + /// The default rights on Discord.com are 648540060672 ([source](https://github.com/spacebarchat/server/issues/878#issuecomment-1234669715)) + /// + /// # Reference + /// See pub struct Rights: u64 { + /// All rights const OPERATOR = 1 << 0; + /// Ability to alter or remove others' applications const MANAGE_APPLICATIONS = 1 << 1; + /// Same as the per-guild [MANAGE_GUILD] permission, but applies to all guilds and DM channels, can join any guild without invite const MANAGE_GUILDS = 1 << 2; + /// Can delete or edit any message they can read const MANAGE_MESSAGES = 1 << 3; + /// Can add, change, define rate limits of other users, + /// can also grant others [BYPASS_RATE_LIMITS] when combined + /// with [BYPASS_RATE_LIMITS] and [MANAGE_USERS]. const MANAGE_RATE_LIMITS = 1 << 4; + /// Can create, alter, enable and disable custom message routing rules in any channel/guild const MANAGE_ROUTING = 1 << 5; + /// Respond to or resolve other users' support tickets const MANAGE_TICKETS = 1 << 6; + /// Can create, alter, remove and ban users; can also create, modify and remove user groups const MANAGE_USERS = 1 << 7; + /// Can manually add members into their guilds and group DMs const ADD_MEMBERS = 1 << 8; + /// Makes the user exempt from all rate limits const BYPASS_RATE_LIMITS = 1 << 9; + /// Can create, edit and remove own applications const CREATE_APPLICATIONS = 1 << 10; + /// Can create guild channels and custom channels const CREATE_CHANNELS = 1 << 11; + /// Can create 1:1 DMs + /// + /// # Notes + /// A user without [SEND_MESSAGES] cannot be added to a DM const CREATE_DMS = 1 << 12; + /// Can create group DMs + /// + /// # Notes + /// A user without [SEND_MESSAGES] cannot be added to a DM const CREATE_DM_GROUPS = 1 << 13; + /// Can create guilds const CREATE_GUILDS = 1 << 14; + /// Can create mass invites in guilds where they have [CREATE_INSTANT_INVITE] const CREATE_INVITES = 1 << 15; + /// Can create roles and per-guild or per-channel permission + /// overrides in the guilds that they have permissions const CREATE_ROLES = 1 << 16; + /// Can create templates for guilds, custom channels and channels with custom routing const CREATE_TEMPLATES = 1 << 17; + /// Can create webhooks in the guilds that they have permissions const CREATE_WEBHOOKS = 1 << 18; + /// Can join guilds by using invites or vanity names const JOIN_GUILDS = 1 << 19; + /// Can modify the pinned messages in the guilds that they have permission const PIN_MESSAGES = 1 << 20; + /// Can react to messages, subject to permissions const SELF_ADD_REACTIONS = 1 << 21; + /// Can delete own messages const SELF_DELETE_MESSAGES = 1 << 22; + /// Can edit own messages const SELF_EDIT_MESSAGES = 1 << 23; + /// Can edit own username, nickname and avatar const SELF_EDIT_NAME = 1 << 24; + /// Can send messages in the channels that they have permissions const SEND_MESSAGES = 1 << 25; + /// Can use voice activities, such as watch together or whiteboard const USE_ACTIVITIES = 1 << 26; + /// Can use video and screenshare in guilds/channels that they have permissions const USE_VIDEO = 1 << 27; + /// Can use voice in guilds/channels that they have permissions const USE_VOICE = 1 << 28; + /// Can create user-specific invites in guilds that they have INVITE_USERS const INVITE_USERS = 1 << 29; + /// Can delete/disable own account const SELF_DELETE_DISABLE = 1 << 30; + /// Can use pay-to-use features once paid const DEBTABLE = 1 << 31; + /// Can earn money using monetization features in guilds that have MONETIZATION_ENABLED const CREDITABLE = 1 << 32; + /// Can kick or ban guild or group DM members in the guilds/groups where they have KICK_MEMBERS or BAN_MEMBERS const KICK_BAN_MEMBERS = 1 << 33; + /// Can leave the guilds or group DMs that they joined on their own (one can always leave a guild or group DMs where they have been force-added) const SELF_LEAVE_GROUPS = 1 << 34; + /// Inverts the presence confidentiality default (OPERATOR's presence is not routed by default, others' are) for a given user const PRESENCE = 1 << 35; + /// Can mark discoverable guilds where they have permissions to mark as discoverable const SELF_ADD_DISCOVERABLE = 1 << 36; + /// Can change anything in the primary guild directory const MANAGE_GUILD_DIRECTORY = 1 << 37; + /// Can send confetti, screenshake and use the random user mention (@someone) const POGGERS = 1 << 38; + /// Can use achievements and cheers const USE_ACHIEVEMENTS = 1 << 39; + /// Can initiate interactions const INITIATE_INTERACTIONS = 1 << 40; + /// Can respond to interactions const RESPOND_TO_INTERACTIONS = 1 << 41; + /// Can send backdated events const SEND_BACKDATED_EVENTS = 1 << 42; + /// Can accept mass (guild) invites const USE_MASS_INVITES = 1 << 43; + /// Can accept user-specific invites and DM requests const ACCEPT_INVITES = 1 << 44; + /// Can modify own flags const SELF_EDIT_FLAGS = 1 << 45; + /// Can modify other's flags const EDIT_FLAGS = 1 << 46; + /// Can manage other's groups const MANAGE_GROUPS = 1 << 47; + /// Can view server stats at /api/policies/stats const VIEW_SERVER_STATS = 1 << 48; + /// Can resend verification emails using /auth/verify/resend const RESEND_VERIFICATION_EMAIL = 1 << 49; } } @@ -60,10 +128,16 @@ impl Rights { (check_operator && self.contains(Rights::OPERATOR)) || self.contains(permission) } + /// Returns whether or not the Rights object has specific rights pub fn has(&self, permission: Rights, check_operator: bool) -> bool { (check_operator && self.contains(Rights::OPERATOR)) || self.contains(permission) } + /// Returns whether or not the Rights object has specific rights. + /// + /// # Notes + /// Unlike has, this returns an Error if we are missing rights + /// and Ok(true) otherwise pub fn has_throw(&self, permission: Rights) -> Result { if self.has(permission, true) { Ok(true) From a4f59fcdf47b40b768dcb69e9338ed2c4af21a20 Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Sat, 29 Jul 2023 11:26:00 +0200 Subject: [PATCH 09/26] Minor doc changes --- src/lib.rs | 1 + src/types/schema/user.rs | 3 +++ src/types/utils/jwt.rs | 6 ++++-- src/types/utils/snowflake.rs | 2 ++ src/voice.rs | 3 ++- 5 files changed, 12 insertions(+), 3 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 8315a4d..6563bed 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -34,6 +34,7 @@ pub struct UrlBundle { } impl UrlBundle { + /// Creates a new UrlBundle from the relevant urls. pub fn new(api: String, wss: String, cdn: String) -> Self { Self { api: UrlBundle::parse_url(api), diff --git a/src/types/schema/user.rs b/src/types/schema/user.rs index c8cf5bb..9946e73 100644 --- a/src/types/schema/user.rs +++ b/src/types/schema/user.rs @@ -6,6 +6,7 @@ use crate::types::Snowflake; #[derive(Debug, Deserialize, Serialize)] #[serde(rename_all = "snake_case")] +/// A schema used to modify a user. pub struct UserModifySchema { pub username: Option, pub avatar: Option, @@ -19,6 +20,8 @@ pub struct UserModifySchema { pub discriminator: Option, } +/// A schema used to create a private channel. +/// /// # Attributes: /// - recipients: The users to include in the private channel /// - access_tokens: The access tokens of users that have granted your app the `gdm.join` scope. Only usable for OAuth2 requests (which can only create group DMs). diff --git a/src/types/utils/jwt.rs b/src/types/utils/jwt.rs index c9f1aa5..951c58a 100644 --- a/src/types/utils/jwt.rs +++ b/src/types/utils/jwt.rs @@ -1,8 +1,8 @@ +#[allow(missing_docs)] +use crate::types::utils::Snowflake; use jsonwebtoken::{encode, EncodingKey, Header}; use serde::{Deserialize, Serialize}; -use crate::types::utils::Snowflake; - pub fn generate_token(id: &Snowflake, email: String, jwt_key: &str) -> String { let claims = Claims::new(&email, id); @@ -11,7 +11,9 @@ pub fn generate_token(id: &Snowflake, email: String, jwt_key: &str) -> String { #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct Claims { + /// When the token expires, unix epoch pub exp: i64, + /// When the token was issued pub iat: i64, pub email: String, pub id: String, diff --git a/src/types/utils/snowflake.rs b/src/types/utils/snowflake.rs index 81f3b5b..b34701a 100644 --- a/src/types/utils/snowflake.rs +++ b/src/types/utils/snowflake.rs @@ -18,6 +18,7 @@ const EPOCH: i64 = 1420070400000; pub struct Snowflake(u64); impl Snowflake { + /// Generates a snowflake for the current epoch. pub fn generate() -> Self { const WORKER_ID: u64 = 0; const PROCESS_ID: u64 = 1; @@ -31,6 +32,7 @@ impl Snowflake { Self(time as u64 | worker | process | increment) } + /// Returns the snowflake's timestamp pub fn timestamp(self) -> DateTime { Utc.timestamp_millis_opt((self.0 >> 22) as i64 + EPOCH) .unwrap() diff --git a/src/voice.rs b/src/voice.rs index 8b13789..c2fcaf2 100644 --- a/src/voice.rs +++ b/src/voice.rs @@ -1 +1,2 @@ - +//! Where the voice chat implementation will be, once it's finished. +//! For development on voice, see the feature/voice branch. From 9c4136644b9d46613e2e150bb37820a2932e1e55 Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Sat, 29 Jul 2023 11:26:10 +0200 Subject: [PATCH 10/26] Document some flags --- src/types/entities/application.rs | 31 ++++++++++++++++++ src/types/entities/role.rs | 54 +++++++++++++++++++++++++++++++ 2 files changed, 85 insertions(+) diff --git a/src/types/entities/application.rs b/src/types/entities/application.rs index 15e259c..d4805e9 100644 --- a/src/types/entities/application.rs +++ b/src/types/entities/application.rs @@ -8,6 +8,8 @@ use crate::types::{Team, User}; #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] #[cfg_attr(feature = "sqlx", derive(sqlx::FromRow))] +/// # Reference +/// See pub struct Application { pub id: Snowflake, pub name: String, @@ -93,6 +95,8 @@ impl Application { } #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +/// # Reference +/// See pub struct InstallParams { pub scopes: Vec, pub permissions: String, @@ -100,21 +104,37 @@ pub struct InstallParams { bitflags! { #[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)] + /// # Reference + /// See pub struct ApplicationFlags: u64 { + /// Indicates if an app uses the Auto Moderation API const APPLICATION_AUTO_MODERATION_RULE_CREATE_BADGE = 1 << 6; + /// Intent required for bots in 100 or more servers to receive presence_update events const GATEWAY_PRESENCE = 1 << 12; + /// Intent required for bots in under 100 servers to receive presence_update events, found on the Bot page in your app's settings on discord.com const GATEWAY_PRESENCE_LIMITED = 1 << 13; + /// Intent required for bots in 100 or more servers to receive member-related events like guild_member_add. + /// See the list of member-related events under GUILD_MEMBERS const GATEWAY_GUILD_MEMBERS = 1 << 14; + /// Intent required for bots in under 100 servers to receive member-related events like guild_member_add, found on the Bot page in your app's settings on discord.com. + /// See the list of member-related events under GUILD_MEMBERS const GATEWAY_GUILD_MEMBERS_LIMITED = 1 << 15; + /// Indicates unusual growth of an app that prevents verification const VERIFICATION_PENDING_GUILD_LIMIT = 1 << 16; + /// Indicates if an app is embedded within the Discord client (currently unavailable publicly) const EMBEDDED = 1 << 17; + /// Intent required for bots in 100 or more servers to receive message content const GATEWAY_MESSAGE_CONTENT = 1 << 18; + /// Intent required for bots in under 100 servers to receive message content, found on the Bot page in your app's settings on discord.com const GATEWAY_MESSAGE_CONTENT_LIMITED = 1 << 19; + /// Indicates if an app has registered slash commands const APPLICATION_COMMAND_BADGE = 1 << 23; } } #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +/// # Reference +/// See pub struct ApplicationCommand { pub id: Snowflake, pub application_id: Snowflake, @@ -124,6 +144,8 @@ pub struct ApplicationCommand { } #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +/// Reference +/// See pub struct ApplicationCommandOption { pub r#type: ApplicationCommandOptionType, pub name: String, @@ -142,15 +164,24 @@ pub struct ApplicationCommandOptionChoice { #[derive(Debug, Clone, Copy, PartialEq, Serialize_repr, Deserialize_repr)] #[cfg_attr(feature = "sqlx", derive(sqlx::Type))] #[repr(i32)] +/// # Reference +/// See pub enum ApplicationCommandOptionType { SubCommand = 1, SubCommandGroup = 2, String = 3, + /// Any integer between -2^53 and 2^53 Integer = 4, Boolean = 5, User = 6, + /// Includes all channel types + categories Channel = 7, Role = 8, + /// Includes users and roles + Mentionable = 9, + /// Any double between -2^53 and 2^53 + Number = 10, + Attachment = 11, } #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] diff --git a/src/types/entities/role.rs b/src/types/entities/role.rs index ef93b5d..0748453 100644 --- a/src/types/entities/role.rs +++ b/src/types/entities/role.rs @@ -54,56 +54,109 @@ pub struct RoleTags { bitflags! { #[derive(Debug, Default, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)] + /// Permissions limit what users of certain roles can do on a Guild to Guild basis. + /// + /// # Reference: + /// See pub struct PermissionFlags: u64 { + /// Allows creation of instant invites const CREATE_INSTANT_INVITE = 1 << 0; + /// Allows kicking members const KICK_MEMBERS = 1 << 1; + /// Allows banning members const BAN_MEMBERS = 1 << 2; + /// Allows all permissions and bypasses channel permission overwrites const ADMINISTRATOR = 1 << 3; + /// Allows management and editing of channels const MANAGE_CHANNELS = 1 << 4; + /// Allows management and editing of the guild and guild settings const MANAGE_GUILD = 1 << 5; + /// Allows for the addition of reactions to messages const ADD_REACTIONS = 1 << 6; + /// Allows viewing of the audit log const VIEW_AUDIT_LOG = 1 << 7; + /// Allows using priority speaker in a voice channel const PRIORITY_SPEAKER = 1 << 8; + /// Allows the user to go live and share their screen const STREAM = 1 << 9; + /// Allows guild members to view a channel, which includes reading messages in text channels and joining voice channels const VIEW_CHANNEL = 1 << 10; + /// Allows sending messages in a channel and creating threads in a forum (does not allow sending messages in threads) const SEND_MESSAGES = 1 << 11; + /// Allows sending /tts messages const SEND_TTS_MESSAGES = 1 << 12; + /// Allows deletion of other users' messages const MANAGE_MESSAGES = 1 << 13; + /// Links sent by users with this permission will be auto-embedded const EMBED_LINKS = 1 << 14; + /// Allows uploading images and files const ATTACH_FILES = 1 << 15; + /// Allows reading of message history const READ_MESSAGE_HISTORY = 1 << 16; + /// Allows using the @everyone tag to notify all users in a channel, and the @here tag to notify all online users in a channel const MENTION_EVERYONE = 1 << 17; + /// Allows the usage of custom emojis from other servers const USE_EXTERNAL_EMOJIS = 1 << 18; + /// Allows viewing guild insights const VIEW_GUILD_INSIGHTS = 1 << 19; + /// Allows joining of a voice channel const CONNECT = 1 << 20; + /// Allows speaking in a voice channel const SPEAK = 1 << 21; + /// Allows muting members in a voice channel const MUTE_MEMBERS = 1 << 22; + /// Allows deafening of members in a voice channel const DEAFEN_MEMBERS = 1 << 23; + /// Allows moving of members between voice channels const MOVE_MEMBERS = 1 << 24; + /// Allows using voice activity (VAD = voice-activity-detection) in a voice channel const USE_VAD = 1 << 25; + /// Allows modification of own nickname const CHANGE_NICKNAME = 1 << 26; + /// Allows modification of other users' nicknames const MANAGE_NICKNAMES = 1 << 27; + /// Allows management and editing of roles const MANAGE_ROLES = 1 << 28; + /// Allows management and editing of webhooks const MANAGE_WEBHOOKS = 1 << 29; + /// Allows management and editing of emojis, stickers, and soundboard sounds const MANAGE_GUILD_EXPRESSIONS = 1 << 30; + /// Allows members to use application commands, including slash commands and context menu commands. const USE_APPLICATION_COMMANDS = 1 << 31; + /// Allows requesting to speak in stage channels. (*This permission is under active development and may be changed or removed.*) const REQUEST_TO_SPEAK = 1 << 32; + /// Allows creating, editing, and deleting scheduled events const MANAGE_EVENTS = 1 << 33; + /// Allows deleting and archiving threads, and viewing all private threads const MANAGE_THREADS = 1 << 34; + /// Allows creating public and announcement threads const CREATE_PUBLIC_THREADS = 1 << 35; + /// Allows creating private threads const CREATE_PRIVATE_THREADS = 1 << 36; + /// Allows the usage of custom stickers from other servers const USE_EXTERNAL_STICKERS = 1 << 37; + /// Allows sending messages in threads const SEND_MESSAGES_IN_THREADS = 1 << 38; + /// Allows using Activities in a voice channel const USE_EMBEDDED_ACTIVITIES = 1 << 39; + /// Allows timing out users to prevent them from sending or reacting to messages in chat and threads, and from speaking in voice and stage channels const MODERATE_MEMBERS = 1 << 40; + /// Allows viewing role subscription insights const VIEW_CREATOR_MONETIZATION_ANALYTICS = 1 << 41; + /// Allows using the soundboard in a voice channel const USE_SOUNDBOARD = 1 << 42; + /// Allows using custom soundboard sounds from other servers const USE_EXTERNAL_SOUNDS = 1 << 45; + /// Allows sending voice messages const SEND_VOICE_MESSAGES = 1 << 46; } } impl PermissionFlags { + /// Returns if the PermissionFlags object has specific permissions + /// + /// # Notes + /// Note that if the object has the [PermissionFlags::ADMINISTRATOR] permission, this always returns true pub fn has_permission(&self, permission: PermissionFlags) -> bool { self.contains(permission) || self.contains(PermissionFlags::ADMINISTRATOR) } @@ -114,6 +167,7 @@ impl PermissionFlags { } /// Creates a String of Permissions from a given [`Vec`] of [`PermissionFlags`]. + /// /// # Example: /// ``` /// use chorus::types::{PermissionFlags}; From abcdd5e1283244ea6dd818728506fd32fd9a8380 Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Sat, 29 Jul 2023 11:45:25 +0200 Subject: [PATCH 11/26] Forgot this since had the lint on my local copy --- src/types/utils/jwt.rs | 1 - 1 file changed, 1 deletion(-) diff --git a/src/types/utils/jwt.rs b/src/types/utils/jwt.rs index 951c58a..ca0aebb 100644 --- a/src/types/utils/jwt.rs +++ b/src/types/utils/jwt.rs @@ -1,4 +1,3 @@ -#[allow(missing_docs)] use crate::types::utils::Snowflake; use jsonwebtoken::{encode, EncodingKey, Header}; use serde::{Deserialize, Serialize}; From b4b9f875203e8d51a278344d6e27e2469929b846 Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Sat, 29 Jul 2023 16:04:08 +0000 Subject: [PATCH 12/26] Capitalise docs Co-authored-by: SpecificProtagonist --- src/types/events/presence.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/types/events/presence.rs b/src/types/events/presence.rs index 0aef27e..c2d985e 100644 --- a/src/types/events/presence.rs +++ b/src/types/events/presence.rs @@ -6,7 +6,7 @@ use serde::{Deserialize, Serialize}; /// Sent by the client to update its status and presence; /// See pub struct UpdatePresence { - /// unix time of when the client went idle, or none if client is not idle + /// Unix time of when the client went idle, or none if client is not idle. pub since: Option, /// the client's status (online, invisible, offline, dnd, idle..) pub status: UserStatus, From 5d49e72461b7c386c415ed83f3e3396d9130f948 Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Sat, 29 Jul 2023 16:04:49 +0000 Subject: [PATCH 13/26] Update src/types/utils/rights.rs Co-authored-by: SpecificProtagonist --- src/types/utils/rights.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/types/utils/rights.rs b/src/types/utils/rights.rs index dc4955a..52d68cd 100644 --- a/src/types/utils/rights.rs +++ b/src/types/utils/rights.rs @@ -78,7 +78,7 @@ bitflags! { const USE_VIDEO = 1 << 27; /// Can use voice in guilds/channels that they have permissions const USE_VOICE = 1 << 28; - /// Can create user-specific invites in guilds that they have INVITE_USERS + /// Can create user-specific invites in guilds that they have the [`INVITE_USERS`] right in. const INVITE_USERS = 1 << 29; /// Can delete/disable own account const SELF_DELETE_DISABLE = 1 << 30; From d4048d8845dc6c1e88b935768bd85110cb9a4c6a Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Sat, 29 Jul 2023 16:05:27 +0000 Subject: [PATCH 14/26] Update src/types/utils/rights.rs Co-authored-by: SpecificProtagonist --- src/types/utils/rights.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/types/utils/rights.rs b/src/types/utils/rights.rs index 52d68cd..666cf17 100644 --- a/src/types/utils/rights.rs +++ b/src/types/utils/rights.rs @@ -84,7 +84,7 @@ bitflags! { const SELF_DELETE_DISABLE = 1 << 30; /// Can use pay-to-use features once paid const DEBTABLE = 1 << 31; - /// Can earn money using monetization features in guilds that have MONETIZATION_ENABLED + /// Can earn money using monetization features in guilds that have [`MonetizationEnabled`](crate::types::types::guild_configuration::GuildFeatures::MonetizationEnabled) const CREDITABLE = 1 << 32; /// Can kick or ban guild or group DM members in the guilds/groups where they have KICK_MEMBERS or BAN_MEMBERS const KICK_BAN_MEMBERS = 1 << 33; From 5ed24eea628bf8a550e7d844c02d54965d0245b5 Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Sat, 29 Jul 2023 16:06:35 +0000 Subject: [PATCH 15/26] Update src/types/utils/rights.rs Co-authored-by: SpecificProtagonist --- src/types/utils/rights.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/types/utils/rights.rs b/src/types/utils/rights.rs index 666cf17..bab08db 100644 --- a/src/types/utils/rights.rs +++ b/src/types/utils/rights.rs @@ -86,7 +86,7 @@ bitflags! { const DEBTABLE = 1 << 31; /// Can earn money using monetization features in guilds that have [`MonetizationEnabled`](crate::types::types::guild_configuration::GuildFeatures::MonetizationEnabled) const CREDITABLE = 1 << 32; - /// Can kick or ban guild or group DM members in the guilds/groups where they have KICK_MEMBERS or BAN_MEMBERS + /// Can kick or ban guild or group DM members in the guilds/groups where they have [`KICK_MEMBERS`](crate::types::PermissionFlags::KICK_MEMBERS) or [`BAN_MEMBERS`](crate::types::PermissionFlags::BAN_MEMBERS) const KICK_BAN_MEMBERS = 1 << 33; /// Can leave the guilds or group DMs that they joined on their own (one can always leave a guild or group DMs where they have been force-added) const SELF_LEAVE_GROUPS = 1 << 34; From 8954fd2ae5127e287155baf6587bf96635207b33 Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Sat, 29 Jul 2023 16:06:49 +0000 Subject: [PATCH 16/26] Update src/types/utils/snowflake.rs Co-authored-by: SpecificProtagonist --- src/types/utils/snowflake.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/types/utils/snowflake.rs b/src/types/utils/snowflake.rs index b34701a..9796084 100644 --- a/src/types/utils/snowflake.rs +++ b/src/types/utils/snowflake.rs @@ -18,7 +18,7 @@ const EPOCH: i64 = 1420070400000; pub struct Snowflake(u64); impl Snowflake { - /// Generates a snowflake for the current epoch. + /// Generates a snowflake for the current timestamp, with worker id 0 and process id 1. pub fn generate() -> Self { const WORKER_ID: u64 = 0; const PROCESS_ID: u64 = 1; From 49801bef101051cf9c19eaaf672b1061cbddfffc Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Sat, 29 Jul 2023 16:07:06 +0000 Subject: [PATCH 17/26] Update src/types/utils/rights.rs Co-authored-by: SpecificProtagonist --- src/types/utils/rights.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/types/utils/rights.rs b/src/types/utils/rights.rs index bab08db..5a3c373 100644 --- a/src/types/utils/rights.rs +++ b/src/types/utils/rights.rs @@ -90,7 +90,7 @@ bitflags! { const KICK_BAN_MEMBERS = 1 << 33; /// Can leave the guilds or group DMs that they joined on their own (one can always leave a guild or group DMs where they have been force-added) const SELF_LEAVE_GROUPS = 1 << 34; - /// Inverts the presence confidentiality default (OPERATOR's presence is not routed by default, others' are) for a given user + /// Inverts the presence confidentiality default ([`OPERATOR`]'s presence is not routed by default, others' are) for a given user const PRESENCE = 1 << 35; /// Can mark discoverable guilds where they have permissions to mark as discoverable const SELF_ADD_DISCOVERABLE = 1 << 36; From 1893dfe0f9c24d4c54b781082cc989a059c45bbe Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Sat, 29 Jul 2023 18:12:38 +0200 Subject: [PATCH 18/26] Permissions with code blocks --- src/api/channels/reactions.rs | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/api/channels/reactions.rs b/src/api/channels/reactions.rs index 467af56..cdf65ce 100644 --- a/src/api/channels/reactions.rs +++ b/src/api/channels/reactions.rs @@ -63,7 +63,7 @@ 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` 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. @@ -89,13 +89,13 @@ impl ReactionMeta { /// Create a reaction on a message. /// - /// This endpoint requires the READ_MESSAGE_HISTORY permission. + /// This endpoint requires the `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` 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. + /// To use custom emoji, the format of the emoji string must be `name:id`. /// /// # Reference /// See @@ -140,12 +140,12 @@ impl ReactionMeta { /// Deletes a user's reaction to a message. /// - /// This endpoint requires the MANAGE_MESSAGES permission. + /// This endpoint requires the `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. + /// Fires a `Message Reaction Remove` Gateway event. /// /// # Reference /// See From b897e44cca1342d9ba3c3469862c5c998b7c0761 Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Sat, 29 Jul 2023 18:12:49 +0200 Subject: [PATCH 19/26] Document a small bit of attachment --- src/types/entities/attachment.rs | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/src/types/entities/attachment.rs b/src/types/entities/attachment.rs index 4261203..75ec860 100644 --- a/src/types/entities/attachment.rs +++ b/src/types/entities/attachment.rs @@ -4,9 +4,12 @@ use crate::types::utils::Snowflake; #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] #[cfg_attr(feature = "sqlx", derive(sqlx::FromRow))] +/// # Reference +/// See pub struct Attachment { pub id: Snowflake, pub filename: String, + /// Max 1024 characters pub description: Option, pub content_type: Option, pub size: u64, @@ -15,7 +18,13 @@ pub struct Attachment { pub height: Option, pub width: Option, pub ephemeral: Option, + /// The duration of the audio file (only for voice messages) pub duration_secs: Option, + /// A Base64 encoded bytearray representing a sampled waveform (only for voice messages) + /// + /// # Notes + /// Note that this is computed on the client side. + /// This means it can be spoofed and isn't necessarily accurate. pub waveform: Option, #[serde(skip_serializing)] #[cfg_attr(feature = "sqlx", sqlx(default))] @@ -26,6 +35,7 @@ pub struct Attachment { pub struct PartialDiscordFileAttachment { pub id: Option, pub filename: String, + /// Max 1024 characters pub description: Option, pub content_type: Option, pub size: Option, @@ -34,7 +44,13 @@ pub struct PartialDiscordFileAttachment { pub height: Option, pub width: Option, pub ephemeral: Option, + /// The duration of the audio file (only for voice messages) pub duration_secs: Option, + /// A Base64 encoded bytearray representing a sampled waveform (only for voice messages) + /// + /// # Notes + /// Note that this is computed on the client side. + /// This means it can be spoofed and isn't necessarily accurate. pub waveform: Option, #[serde(skip_serializing)] pub content: Vec, @@ -62,6 +78,7 @@ impl PartialDiscordFileAttachment { (content, updated_struct) } + /// Moves `self.filename` out of `self` and returns it. pub fn move_filename(self) -> (String, PartialDiscordFileAttachment) { let filename = self.filename; let updated_struct = PartialDiscordFileAttachment { @@ -83,6 +100,7 @@ impl PartialDiscordFileAttachment { (filename, updated_struct) } + /// Moves `self.content_type` out of `self` and returns it. pub fn move_content_type(self) -> (Option, PartialDiscordFileAttachment) { let content_type = self.content_type; let updated_struct = PartialDiscordFileAttachment { From 499faefa5169a2dc0d0307355e273bb2e1368e1f Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Sun, 30 Jul 2023 08:26:26 +0200 Subject: [PATCH 20/26] Documemtaiom --- src/api/auth/login.rs | 1 + src/api/auth/register.rs | 1 + src/api/channels/channels.rs | 20 ++++++++++++++++++-- src/api/channels/messages.rs | 9 ++++++++- src/api/channels/permissions.rs | 6 ++++++ src/api/users/users.rs | 19 +++++++++++++++++++ src/types/entities/channel.rs | 32 ++++++++++++++++++++++++++++++++ src/types/utils/snowflake.rs | 2 ++ 8 files changed, 87 insertions(+), 3 deletions(-) diff --git a/src/api/auth/login.rs b/src/api/auth/login.rs index 60ee52b..4cc58bb 100644 --- a/src/api/auth/login.rs +++ b/src/api/auth/login.rs @@ -13,6 +13,7 @@ use crate::types::{GatewayIdentifyPayload, LoginResult, LoginSchema}; impl Instance { /// Logs into an existing account on the spacebar server. + // TODO: Couldn't find reference pub async fn login_account(&mut self, login_schema: &LoginSchema) -> ChorusResult { let endpoint_url = self.urls.api.clone() + "/auth/login"; let chorus_request = ChorusRequest { diff --git a/src/api/auth/register.rs b/src/api/auth/register.rs index 630ad9d..ae41c47 100644 --- a/src/api/auth/register.rs +++ b/src/api/auth/register.rs @@ -15,6 +15,7 @@ use crate::{ impl Instance { /// Registers a new user on the server. + // TODO: Couldn't find reference pub async fn register_account( &mut self, register_schema: &RegisterSchema, diff --git a/src/api/channels/channels.rs b/src/api/channels/channels.rs index db94056..0f6d64a 100644 --- a/src/api/channels/channels.rs +++ b/src/api/channels/channels.rs @@ -12,6 +12,9 @@ use crate::{ impl Channel { /// Retrieves a channel from the server. + /// + /// # Reference + /// See pub async fn get(user: &mut UserMeta, channel_id: Snowflake) -> ChorusResult { let url = user.belongs_to.borrow().urls.api.clone(); let chorus_request = ChorusRequest { @@ -24,6 +27,9 @@ impl Channel { } /// Deletes self. + /// + /// # Reference + /// See pub async fn delete(self, user: &mut UserMeta) -> ChorusResult<()> { let chorus_request = ChorusRequest { request: Client::new() @@ -40,6 +46,9 @@ impl Channel { /// Modifies a channel with the provided data. /// Returns the new Channel. + /// + /// # Reference + /// See pub async fn modify( &self, modify_data: ChannelModifySchema, @@ -61,6 +70,9 @@ impl Channel { } /// Fetches recent messages from a channel. + /// + /// # Reference + /// See pub async fn messages( range: GetChannelMessagesSchema, channel_id: Snowflake, @@ -83,8 +95,10 @@ impl Channel { .await } + /// Adds a recipient to a group DM. + /// /// # Reference: - /// Read: + /// See pub async fn add_channel_recipient( &self, recipient_id: Snowflake, @@ -110,8 +124,10 @@ impl Channel { .await } + /// Removes a recipient from a group DM. + /// /// # Reference: - /// Read: + /// See pub async fn remove_channel_recipient( &self, recipient_id: Snowflake, diff --git a/src/api/channels/messages.rs b/src/api/channels/messages.rs index 9c06f6f..5f1745b 100644 --- a/src/api/channels/messages.rs +++ b/src/api/channels/messages.rs @@ -12,6 +12,9 @@ use crate::types::{Message, MessageSendSchema, Snowflake}; impl Message { /// Sends a message in the channel with the provided channel_id. /// Returns the sent message. + /// + /// # Reference + /// See pub async fn send( user: &mut UserMeta, channel_id: Snowflake, @@ -71,8 +74,12 @@ impl Message { impl UserMeta { /// Sends a message in the channel with the provided channel_id. /// Returns the sent message. + /// /// # Notes - /// Shorthand call for Message::send() + /// Shorthand call for [`Message::send`] + /// + /// # Reference + /// See pub async fn send_message( &mut self, message: MessageSendSchema, diff --git a/src/api/channels/permissions.rs b/src/api/channels/permissions.rs index 57feb5d..d68034e 100644 --- a/src/api/channels/permissions.rs +++ b/src/api/channels/permissions.rs @@ -11,6 +11,9 @@ use crate::{ impl types::Channel { /// Edits the permission overwrites for a channel. + /// + /// # Reference + /// See pub async fn edit_permissions( user: &mut UserMeta, channel_id: Snowflake, @@ -38,6 +41,9 @@ impl types::Channel { } /// Deletes a permission overwrite for a channel. + /// + /// # Reference + /// See pub async fn delete_permission( user: &mut UserMeta, channel_id: Snowflake, diff --git a/src/api/users/users.rs b/src/api/users/users.rs index f673ee3..16c2560 100644 --- a/src/api/users/users.rs +++ b/src/api/users/users.rs @@ -16,6 +16,10 @@ impl UserMeta { /// /// # Notes /// This function is a wrapper around [`User::get`]. + /// + /// # Reference + /// See and + /// pub async fn get(user: &mut UserMeta, id: Option<&String>) -> ChorusResult { User::get(user, id).await } @@ -33,6 +37,9 @@ impl UserMeta { } /// Modifies the current user's representation. (See [`User`]) + /// + /// # Reference + /// See pub async fn modify(&mut self, modify_schema: UserModifySchema) -> ChorusResult { if modify_schema.new_password.is_some() || modify_schema.email.is_some() @@ -57,6 +64,9 @@ impl UserMeta { } /// Deletes the user from the Instance. + /// + /// # Reference + /// See pub async fn delete(mut self) -> ChorusResult<()> { let request = Client::new() .post(format!( @@ -74,6 +84,10 @@ impl UserMeta { impl User { /// Gets a user by id, or if the id is None, gets the current user. + /// + /// # Reference + /// See and + /// pub async fn get(user: &mut UserMeta, id: Option<&String>) -> ChorusResult { let url_api = user.belongs_to.borrow().urls.api.clone(); let url = if id.is_none() { @@ -96,6 +110,7 @@ impl User { } /// Gets the user's settings. + // TODO: Couldn't find reference pub async fn get_settings( token: &String, url_api: &String, @@ -127,6 +142,10 @@ impl Instance { /// /// # Notes /// This function is a wrapper around [`User::get`]. + /// + /// # Reference + /// See and + /// pub async fn get_user(&mut self, token: String, id: Option<&String>) -> ChorusResult { let mut user = UserMeta::shell(Rc::new(RefCell::new(self.clone())), token).await; let result = User::get(&mut user, id).await; diff --git a/src/types/entities/channel.rs b/src/types/entities/channel.rs index 154b83c..98aa9ed 100644 --- a/src/types/entities/channel.rs +++ b/src/types/entities/channel.rs @@ -12,6 +12,10 @@ use crate::types::{ #[derive(Default, Debug, Serialize, Deserialize, Clone, PartialEq, Eq, Updateable)] #[cfg_attr(feature = "sqlx", derive(sqlx::FromRow))] +/// Represents a guild of private channel +/// +/// # Reference +/// See pub struct Channel { pub application_id: Option, #[cfg(feature = "sqlx")] @@ -120,27 +124,55 @@ pub struct DefaultReaction { #[cfg_attr(feature = "sqlx", derive(sqlx::Type))] #[serde(rename_all = "SCREAMING_SNAKE_CASE")] #[repr(i32)] +/// # Reference +/// See pub enum ChannelType { #[default] + /// A text channel within a guild GuildText = 0, + /// A private channel between two users Dm = 1, + /// A voice channel within a guild GuildVoice = 2, + /// A private channel between multiple users GroupDm = 3, + /// An organizational category that contains up to 50 channels GuildCategory = 4, + /// Similar to [GuildText], a channel that users can follow and crosspost into their own guild GuildNews = 5, + /// A channel in which game developers can sell their game on Discord + /// + /// # Note + /// Deprecated. GuildStore = 6, + // FIXME userdoccers says 7 is GuildLfg, is this a spacebar specific thing? Encrypted = 7, + // FIXME userdoccers says 8 is LfgGuildDm, is this a spacebar specific thing? EncryptedThreads = 8, + // FIXME userdoccers says 9 is ThreadAlpha, was this changed? Transactional = 9, + /// A thread within a [GuildNews] channel GuildNewsThread = 10, + /// A thread within a [GuildText], [GuildForum], or [GuildMedia] channel GuildPublicThread = 11, + /// A thread within a [GuildText] channel, that is only viewable by those invited and those with the [ManageThreads] permission GuildPrivateThread = 12, + /// A voice channel for hosting events with an audience in a guild GuildStageVoice = 13, + /// The main channel in a hub containing the listed guilds Directory = 14, + /// A channel that can only contain threads GuildForum = 15, + /// A channel that can only contain threads in a gallery view + GuildMedia = 16, + // TODO: Couldn't find reference TicketTracker = 33, + // TODO: Couldn't find reference Kanban = 34, + // TODO: Couldn't find reference VoicelessWhiteboard = 35, + // TODO: Couldn't find reference CustomStart = 64, + // TODO: Couldn't find reference Unhandled = 255, } diff --git a/src/types/utils/snowflake.rs b/src/types/utils/snowflake.rs index 9796084..a9f572b 100644 --- a/src/types/utils/snowflake.rs +++ b/src/types/utils/snowflake.rs @@ -11,6 +11,8 @@ use sqlx::Type; const EPOCH: i64 = 1420070400000; /// Unique identifier including a timestamp. +/// +/// # Reference /// See #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)] #[cfg_attr(feature = "sqlx", derive(Type))] From 51679e773c024c9b85ba03099681b8524427f8bb Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Sun, 30 Jul 2023 08:31:12 +0200 Subject: [PATCH 21/26] Fix broken links --- src/types/entities/channel.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/types/entities/channel.rs b/src/types/entities/channel.rs index 98aa9ed..43ca54b 100644 --- a/src/types/entities/channel.rs +++ b/src/types/entities/channel.rs @@ -138,7 +138,7 @@ pub enum ChannelType { GroupDm = 3, /// An organizational category that contains up to 50 channels GuildCategory = 4, - /// Similar to [GuildText], a channel that users can follow and crosspost into their own guild + /// Similar to [GuildText](ChannelType::GuildText), a channel that users can follow and crosspost into their own guild GuildNews = 5, /// A channel in which game developers can sell their game on Discord /// @@ -151,11 +151,11 @@ pub enum ChannelType { EncryptedThreads = 8, // FIXME userdoccers says 9 is ThreadAlpha, was this changed? Transactional = 9, - /// A thread within a [GuildNews] channel + /// A thread within a [GuildNews](ChannelType::GuildNews) channel GuildNewsThread = 10, - /// A thread within a [GuildText], [GuildForum], or [GuildMedia] channel + /// A thread within a [GuildText](ChannelType::GuildText), [GuildForum](ChannelType::GuildForum), or [GuildMedia](ChannelType::GuildMedia) channel GuildPublicThread = 11, - /// A thread within a [GuildText] channel, that is only viewable by those invited and those with the [ManageThreads] permission + /// A thread within a [GuildText](ChannelType::GuildText) channel, that is only viewable by those invited and those with the [MANAGE_THREADS](crate::types::entities::PermissionFlags::MANAGE_THREADS) permission GuildPrivateThread = 12, /// A voice channel for hosting events with an audience in a guild GuildStageVoice = 13, From b99bcef1f6cf58995fa74ab969e7722ecf8b017f Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Sun, 30 Jul 2023 09:04:31 +0200 Subject: [PATCH 22/26] Guilds + Channels --- src/api/guilds/guilds.rs | 29 ++++++++++++++++++++++++++++- src/api/guilds/member.rs | 9 +++++++++ src/api/guilds/roles.rs | 20 ++++++++++++++------ src/types/entities/channel.rs | 14 ++++++++++++++ 4 files changed, 65 insertions(+), 7 deletions(-) diff --git a/src/api/guilds/guilds.rs b/src/api/guilds/guilds.rs index 9b9d87f..f598414 100644 --- a/src/api/guilds/guilds.rs +++ b/src/api/guilds/guilds.rs @@ -12,6 +12,9 @@ use crate::types::{Channel, ChannelCreateSchema, Guild, GuildCreateSchema}; impl Guild { /// Creates a new guild. + /// + /// # Reference + /// See pub async fn create( user: &mut UserMeta, guild_create_schema: GuildCreateSchema, @@ -41,6 +44,9 @@ impl Guild { /// Ok(_) => println!("Guild deleted successfully"), /// } /// ``` + /// + /// # Reference + /// See pub async fn delete(user: &mut UserMeta, guild_id: Snowflake) -> ChorusResult<()> { let url = format!( "{}/guilds/{}/delete/", @@ -57,6 +63,14 @@ impl Guild { } /// Creates a new channel in a guild. + /// + /// Requires the [MANAGE_CHANNELS](crate::types::PermissionFlags::MANAGE_CHANNELS) permission. + /// + /// # Notes + /// This method is a wrapper for [Channel::create]. + /// + /// # Reference + /// See pub async fn create_channel( &self, user: &mut UserMeta, @@ -65,7 +79,12 @@ impl Guild { Channel::create(user, self.id, schema).await } - /// Returns a list of the guild's channels + /// Returns a list of the guild's channels. + /// + /// Doesn't include threads. + /// + /// # Reference + /// See pub async fn channels(&self, user: &mut UserMeta) -> ChorusResult> { let chorus_request = ChorusRequest { request: Client::new() @@ -97,6 +116,9 @@ impl Guild { } /// Fetches a guild by its id. + /// + /// # Reference + /// See pub async fn get(guild_id: Snowflake, user: &mut UserMeta) -> ChorusResult { let chorus_request = ChorusRequest { request: Client::new() @@ -115,6 +137,11 @@ impl Guild { impl Channel { /// Creates a new channel in a guild. + /// + /// Requires the [MANAGE_CHANNELS](crate::types::PermissionFlags::MANAGE_CHANNELS) permission. + /// + /// # Reference + /// See pub async fn create( user: &mut UserMeta, guild_id: Snowflake, diff --git a/src/api/guilds/member.rs b/src/api/guilds/member.rs index 1cf1a08..06b5154 100644 --- a/src/api/guilds/member.rs +++ b/src/api/guilds/member.rs @@ -10,6 +10,9 @@ use crate::{ impl types::GuildMember { /// Retrieves a guild member. + /// + /// # Reference + /// See pub async fn get( user: &mut UserMeta, guild_id: Snowflake, @@ -31,6 +34,9 @@ impl types::GuildMember { } /// Adds a role to a guild member. + /// + /// # Reference + /// See pub async fn add_role( user: &mut UserMeta, guild_id: Snowflake, @@ -52,6 +58,9 @@ impl types::GuildMember { } /// Removes a role from a guild member. + /// + /// # Reference + /// See pub async fn remove_role( user: &mut UserMeta, guild_id: Snowflake, diff --git a/src/api/guilds/roles.rs b/src/api/guilds/roles.rs index 81aca03..e76749e 100644 --- a/src/api/guilds/roles.rs +++ b/src/api/guilds/roles.rs @@ -12,11 +12,12 @@ use crate::{ impl types::RoleObject { /// Retrieves a list of roles for a given guild. /// - /// Returns Ok(None) if the guild has no roles. + /// # Reference + /// See pub async fn get_all( user: &mut UserMeta, guild_id: Snowflake, - ) -> ChorusResult>> { + ) -> ChorusResult> { let url = format!( "{}/guilds/{}/roles/", user.belongs_to.borrow().urls.api, @@ -30,13 +31,11 @@ impl types::RoleObject { .deserialize_response::>(user) .await .unwrap(); - if roles.is_empty() { - return Ok(None); - } - Ok(Some(roles)) + Ok(roles) } /// Retrieves a single role for a given guild. + // TODO: Couldn't find reference pub async fn get( user: &mut UserMeta, guild_id: Snowflake, @@ -58,6 +57,9 @@ impl types::RoleObject { } /// Creates a new role for a given guild. + /// + /// # Reference + /// See pub async fn create( user: &mut UserMeta, guild_id: Snowflake, @@ -83,6 +85,9 @@ impl types::RoleObject { } /// Updates the position of a role in a given guild's hierarchy. + /// + /// # Reference + /// See pub async fn position_update( user: &mut UserMeta, guild_id: Snowflake, @@ -110,6 +115,9 @@ impl types::RoleObject { } /// Updates a role in a guild. + /// + /// # Reference + /// See pub async fn update( user: &mut UserMeta, guild_id: Snowflake, diff --git a/src/types/entities/channel.rs b/src/types/entities/channel.rs index 43ca54b..60304f9 100644 --- a/src/types/entities/channel.rs +++ b/src/types/entities/channel.rs @@ -72,9 +72,15 @@ pub struct Channel { } #[derive(Debug, Deserialize, Serialize, Clone, PartialEq, Eq)] +/// A tag that can be applied to a thread in a [ChannelType::GuildForum] or [ChannelType::GuildMedia] channel. +/// +/// # Reference +/// See pub struct Tag { pub id: Snowflake, + /// The name of the tag (max 20 characters) pub name: String, + /// Whether this tag can only be added to or removed from threads by members with the [MANAGE_THREADS](crate::types::PermissionFlags::MANAGE_THREADS) permission pub moderated: bool, pub emoji_id: Option, pub emoji_name: Option, @@ -95,6 +101,8 @@ pub struct PermissionOverwrite { } #[derive(Debug, Deserialize, Serialize, Clone, PartialEq, Eq)] +/// # Reference +/// See pub struct ThreadMetadata { pub archived: bool, pub auto_archive_duration: i32, @@ -105,6 +113,8 @@ pub struct ThreadMetadata { } #[derive(Default, Debug, Deserialize, Serialize, Clone, PartialEq, Eq)] +/// # Reference +/// See pub struct ThreadMember { pub id: Option, pub user_id: Option, @@ -114,6 +124,10 @@ pub struct ThreadMember { } #[derive(Debug, Deserialize, Serialize, Clone, PartialEq, Eq)] +/// Specifies the emoji to use as the default way to react to a [ChannelType::GuildForum] or [ChannelType::GuildMedia] channel post. +/// +/// # Reference +/// See pub struct DefaultReaction { #[serde(default)] pub emoji_id: Option, From dcb518bd3c47171c47bdf29e39de9565b4ded6f3 Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Sun, 30 Jul 2023 09:10:32 +0200 Subject: [PATCH 23/26] Fix the test --- tests/roles.rs | 1 - 1 file changed, 1 deletion(-) diff --git a/tests/roles.rs b/tests/roles.rs index 1675367..f45fb62 100644 --- a/tests/roles.rs +++ b/tests/roles.rs @@ -24,7 +24,6 @@ async fn create_and_get_roles() { let expected = types::RoleObject::get_all(&mut bundle.user, guild) .await - .unwrap() .unwrap()[2] .clone(); From 4e4e279333df85bbb665689e73011cca503e5046 Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Mon, 31 Jul 2023 10:01:25 +0200 Subject: [PATCH 24/26] Docs --- src/api/channels/channels.rs | 17 +++++++++++++++++ src/api/channels/permissions.rs | 14 ++++++++++++-- src/api/channels/reactions.rs | 18 +++++------------- src/api/guilds/guilds.rs | 4 +++- src/api/guilds/member.rs | 4 ++++ src/api/guilds/roles.rs | 6 ++++++ src/api/invites/mod.rs | 12 +++++------- src/api/policies/instance/instance.rs | 6 ++++++ src/api/users/channels.rs | 5 ++++- src/api/users/guilds.rs | 6 ++++-- src/ratelimiter.rs | 7 +++++++ src/types/entities/emoji.rs | 2 ++ src/types/entities/guild_member.rs | 4 ++++ src/types/entities/message.rs | 10 ++++++++-- src/types/entities/sticker.rs | 10 ++++++++++ 15 files changed, 97 insertions(+), 28 deletions(-) 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, From 9f39943b15f9d2de59270192c4a1ce7cd9037424 Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Mon, 31 Jul 2023 10:07:56 +0200 Subject: [PATCH 25/26] Goof --- src/api/channels/channels.rs | 4 ++-- src/api/invites/mod.rs | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/api/channels/channels.rs b/src/api/channels/channels.rs index ba99a8f..bf2c48c 100644 --- a/src/api/channels/channels.rs +++ b/src/api/channels/channels.rs @@ -28,7 +28,7 @@ impl Channel { /// Deletes self. /// - /// Requires the [`MANAGE_CHANNEL`](crate::types::PermissionFlags::MANAGE_CHANNEL) permission in a guild, or + /// Requires the [`MANAGE_CHANNELS`](crate::types::PermissionFlags::MANAGE_CHANNELS) permission in a guild, or /// the [`MANAGE_THREADS`](crate::types::PermissionFlags::MANAGE_THREADS) permission if the channel is a thread. /// /// # Reference @@ -50,7 +50,7 @@ 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. + /// Requires the [`MANAGE_CHANNELS`](crate::types::PermissionFlags::MANAGE_CHANNELS) 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 diff --git a/src/api/invites/mod.rs b/src/api/invites/mod.rs index 948a785..9492d8e 100644 --- a/src/api/invites/mod.rs +++ b/src/api/invites/mod.rs @@ -60,7 +60,7 @@ 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`](crate::types::PermissionFlags::CRATE_INSTANT_INVITE) permission. + /// For guild channels, the endpoint requires the [`CREATE_INSTANT_INVITE`](crate::types::PermissionFlags::CREATE_INSTANT_INVITE) permission. /// /// # Reference /// See From 6cbde1a04b43f2234ba0b51bb4f1bee2bf2adc4b Mon Sep 17 00:00:00 2001 From: kozabrada123 <59031733+kozabrada123@users.noreply.github.com> Date: Mon, 31 Jul 2023 10:28:18 +0200 Subject: [PATCH 26/26] Fix missing references to the best of my ability --- src/api/auth/login.rs | 4 +++- src/api/auth/register.rs | 4 +++- src/api/guilds/roles.rs | 4 +++- src/api/users/users.rs | 4 +++- 4 files changed, 12 insertions(+), 4 deletions(-) diff --git a/src/api/auth/login.rs b/src/api/auth/login.rs index 4cc58bb..a360170 100644 --- a/src/api/auth/login.rs +++ b/src/api/auth/login.rs @@ -13,7 +13,9 @@ use crate::types::{GatewayIdentifyPayload, LoginResult, LoginSchema}; impl Instance { /// Logs into an existing account on the spacebar server. - // TODO: Couldn't find reference + /// + /// # Reference + /// See pub async fn login_account(&mut self, login_schema: &LoginSchema) -> ChorusResult { let endpoint_url = self.urls.api.clone() + "/auth/login"; let chorus_request = ChorusRequest { diff --git a/src/api/auth/register.rs b/src/api/auth/register.rs index ae41c47..f1f279e 100644 --- a/src/api/auth/register.rs +++ b/src/api/auth/register.rs @@ -15,7 +15,9 @@ use crate::{ impl Instance { /// Registers a new user on the server. - // TODO: Couldn't find reference + /// + /// # Reference + /// See pub async fn register_account( &mut self, register_schema: &RegisterSchema, diff --git a/src/api/guilds/roles.rs b/src/api/guilds/roles.rs index 1134332..2787400 100644 --- a/src/api/guilds/roles.rs +++ b/src/api/guilds/roles.rs @@ -35,7 +35,9 @@ impl types::RoleObject { } /// Retrieves a single role for a given guild. - // TODO: Couldn't find reference + /// + /// # Reference + /// See pub async fn get( user: &mut UserMeta, guild_id: Snowflake, diff --git a/src/api/users/users.rs b/src/api/users/users.rs index 16c2560..3d95e54 100644 --- a/src/api/users/users.rs +++ b/src/api/users/users.rs @@ -110,7 +110,9 @@ impl User { } /// Gets the user's settings. - // TODO: Couldn't find reference + /// + /// # Reference + /// See pub async fn get_settings( token: &String, url_api: &String,