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] 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()