diff --git a/src/api/auth/login.rs b/src/api/auth/login.rs
index 68604d9..a360170 100644
--- a/src/api/auth/login.rs
+++ b/src/api/auth/login.rs
@@ -12,6 +12,10 @@ use crate::ratelimiter::ChorusRequest;
use crate::types::{GatewayIdentifyPayload, LoginResult, LoginSchema};
impl Instance {
+ /// Logs into an existing account on the spacebar server.
+ ///
+ /// # 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 e818d82..f1f279e 100644
--- a/src/api/auth/register.rs
+++ b/src/api/auth/register.rs
@@ -14,15 +14,10 @@ use crate::{
};
impl Instance {
- /// Registers a new user on the Spacebar server.
+ /// Registers a new user on the server.
///
- /// # Arguments
- ///
- /// * `register_schema` - The [`RegisterSchema`] that contains all the information that is needed to register a new user.
- ///
- /// # Errors
- ///
- /// * [`ChorusLibError`] - If the server does not respond.
+ /// # Reference
+ /// See
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 df8e290..bf2c48c 100644
--- a/src/api/channels/channels.rs
+++ b/src/api/channels/channels.rs
@@ -11,6 +11,10 @@ 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 {
@@ -22,19 +26,13 @@ impl Channel {
chorus_request.deserialize_response::(user).await
}
- /// Deletes a channel.
+ /// Deletes self.
///
- /// # Arguments
+ /// 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.
///
- /// * `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.
+ /// # Reference
+ /// See
pub async fn delete(self, user: &mut UserMeta) -> ChorusResult<()> {
let chorus_request = ChorusRequest {
request: Client::new()
@@ -49,20 +47,20 @@ impl Channel {
chorus_request.handle_request_as_result(user).await
}
- /// Modifies a channel.
+ /// Modifies a channel with the provided data.
+ /// Returns the new Channel.
///
- /// # Arguments
+ /// Requires the [`MANAGE_CHANNELS`](crate::types::PermissionFlags::MANAGE_CHANNELS) permission in a guild.
///
- /// * `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.
+ /// 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).
///
- /// # Returns
+ /// 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.
///
- /// A `Result` that contains a `Channel` object if the request was successful, or an `ChorusLibError` if an error occurred during the request.
+ /// # Reference
+ /// See
pub async fn modify(
&self,
modify_data: ChannelModifySchema,
@@ -83,6 +81,15 @@ impl Channel {
chorus_request.deserialize_response::(user).await
}
+ /// 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(
range: GetChannelMessagesSchema,
channel_id: Snowflake,
@@ -105,8 +112,10 @@ impl Channel {
.await
}
+ /// Adds a recipient to a group DM.
+ ///
/// # Reference:
- /// Read:
+ /// See
pub async fn add_channel_recipient(
&self,
recipient_id: Snowflake,
@@ -132,8 +141,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 6beec7f..5f1745b 100644
--- a/src/api/channels/messages.rs
+++ b/src/api/channels/messages.rs
@@ -4,16 +4,22 @@ 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, 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,
mut message: MessageSendSchema,
- ) -> Result {
+ ) -> ChorusResult {
let url_api = user.belongs_to.borrow().urls.api.clone();
if message.attachments.is_none() {
@@ -66,11 +72,19 @@ 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`]
+ ///
+ /// # Reference
+ /// See
pub async fn send_message(
&mut self,
message: MessageSendSchema,
channel_id: Snowflake,
- ) -> Result {
+ ) -> ChorusResult {
Message::send(self, channel_id, message).await
}
}
diff --git a/src/api/channels/permissions.rs b/src/api/channels/permissions.rs
index bc666ff..7c83d85 100644
--- a/src/api/channels/permissions.rs
+++ b/src/api/channels/permissions.rs
@@ -10,17 +10,16 @@ use crate::{
};
impl types::Channel {
- /// Edits the permission overwrites for a channel.
+ /// Edits the permission overwrites for a user or role in a channel.
///
- /// # Arguments
+ /// Only usable for guild channels.
///
- /// * `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.
+ /// 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).
///
- /// # Returns
- ///
- /// This function returns a result that is either [`Ok(())`] if the request is successful, or an [`Err(ChorusLibError)`].
+ /// # Reference
+ /// See
pub async fn edit_permissions(
user: &mut UserMeta,
channel_id: Snowflake,
@@ -47,17 +46,14 @@ 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.
///
- /// # Arguments
+ /// Only usable for guild channels.
///
- /// * `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.
+ /// Requires the [`MANAGE_ROLES`](crate::types::PermissionFlags::MANAGE_ROLES) permission.
///
- /// # Returns
- ///
- /// This function returns a Result that is either [`Ok(())`] if the request is successfulm or an [`Err(ChorusLibError)`].
+ /// # Reference
+ /// See
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 35dbb94..b7b221f 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,
@@ -18,14 +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::ChorusLibError`] if something went wrong.
- /// Fires a `Message Reaction Remove All` Gateway event.
+ ///
+ /// This endpoint requires the [`MANAGE_MESSAGES`](crate::types::PermissionFlags::MANAGE_MESSAGES) permission.
+ ///
/// # Reference
- /// See [https://discord.com/developers/docs/resources/channel#delete-all-reactions](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/",
@@ -41,15 +36,12 @@ 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 [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/{}/",
@@ -67,18 +59,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`](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.
+ ///
/// # 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/{}/",
@@ -94,21 +83,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::ChorusLibError`].
- /// # Reference
- /// See [https://discord.com/developers/docs/resources/channel#create-reaction](https://discord.com/developers/docs/resources/channel#create-reaction)
+ /// Create a reaction on a message.
///
+ /// 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`](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`.
+ ///
+ /// # Reference
+ /// See
pub async fn create(&self, emoji: &str, user: &mut UserMeta) -> ChorusResult<()> {
let url = format!(
"{}/channels/{}/messages/{}/reactions/{}/@me/",
@@ -124,17 +110,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::ChorusLibError`].
- /// Fires a `Message Reaction Remove` Gateway event.
+ /// 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.
+ ///
/// # 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/",
@@ -150,19 +132,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 `Result` containing [`()`] or a [`crate::errors::ChorusLibError`].
- /// Fires a Message Reaction Remove Gateway event.
+ /// Deletes a user's reaction to a message.
+ ///
+ /// 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.
+ ///
/// # 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/guilds.rs b/src/api/guilds/guilds.rs
index 3654698..43a8cdf 100644
--- a/src/api/guilds/guilds.rs
+++ b/src/api/guilds/guilds.rs
@@ -11,22 +11,10 @@ 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.
///
+ /// # Reference
+ /// See
pub async fn create(
user: &mut UserMeta,
guild_create_schema: GuildCreateSchema,
@@ -42,17 +30,9 @@ impl Guild {
chorus_request.deserialize_response::(user).await
}
- /// Deletes a guild.
+ /// Deletes a guild by its id.
///
- /// # 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 `()`.
+ /// User must be the owner.
///
/// # Example
///
@@ -61,11 +41,14 @@ 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"),
/// }
/// ```
+ ///
+ /// # Reference
+ /// See
pub async fn delete(user: &mut UserMeta, guild_id: Snowflake) -> ChorusResult<()> {
let url = format!(
"{}/guilds/{}/delete/",
@@ -81,19 +64,15 @@ impl Guild {
chorus_request.handle_request_as_result(user).await
}
- /// Sends a request to create a new channel in the guild.
+ /// Creates a new channel in a guild.
///
- /// # Arguments
+ /// Requires the [MANAGE_CHANNELS](crate::types::PermissionFlags::MANAGE_CHANNELS) permission.
///
- /// * `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.
+ /// # Notes
+ /// This method is a wrapper for [Channel::create].
///
- /// # Returns
- ///
- /// A `Result` containing a `reqwest::Response` if the request was successful, or an `ChorusLibError` if there was an error.
+ /// # Reference
+ /// See
pub async fn create_channel(
&self,
user: &mut UserMeta,
@@ -102,15 +81,12 @@ 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.
+ /// Returns a list of the guild's channels.
///
- /// # 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.
+ /// Doesn't include threads.
///
+ /// # Reference
+ /// See
pub async fn channels(&self, user: &mut UserMeta) -> ChorusResult> {
let chorus_request = ChorusRequest {
request: Client::new()
@@ -141,16 +117,10 @@ 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.
+ /// 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()
@@ -168,20 +138,12 @@ impl Guild {
}
impl Channel {
- /// Sends a request to create a new channel in a guild.
+ /// Creates a new channel in a guild.
///
- /// # Arguments
+ /// Requires the [MANAGE_CHANNELS](crate::types::PermissionFlags::MANAGE_CHANNELS) permission.
///
- /// * `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.
+ /// # 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 5fa99cd..d3e0e80 100644
--- a/src/api/guilds/member.rs
+++ b/src/api/guilds/member.rs
@@ -5,26 +5,19 @@ use crate::{
errors::ChorusResult,
instance::UserMeta,
ratelimiter::ChorusRequest,
- types::{self, Snowflake},
+ types::{self, GuildMember, Snowflake},
};
impl types::GuildMember {
- /// Retrieves a guild member by their ID.
+ /// Retrieves 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.
- ///
- /// # Returns
- ///
- /// A [`Result`] containing a [`GuildMember`] if the request succeeds, or a [`ChorusLibError`] if the request fails.
+ /// # Reference
+ /// See
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,22 +29,16 @@ impl types::GuildMember {
limit_type: LimitType::Guild(guild_id),
};
chorus_request
- .deserialize_response::(user)
+ .deserialize_response::(user)
.await
}
/// Adds a role to a guild member.
///
- /// # Arguments
+ /// Requires the [`MANAGE_ROLES`](crate::types::PermissionFlags::MANAGE_ROLES) permission.
///
- /// * `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
- ///
- /// An `Result` containing a `ChorusLibError` if the request fails, or `()` if the request succeeds.
+ /// # Reference
+ /// See
pub async fn add_role(
user: &mut UserMeta,
guild_id: Snowflake,
@@ -74,16 +61,10 @@ impl types::GuildMember {
/// Removes a role from a guild member.
///
- /// # Arguments
+ /// Requires the [`MANAGE_ROLES`](crate::types::PermissionFlags::MANAGE_ROLES) permission.
///
- /// * `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 `Result` containing a `ChorusLibError` if the request fails, or `()` if the request succeeds.
+ /// # 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 1d1bc68..2787400 100644
--- a/src/api/guilds/roles.rs
+++ b/src/api/guilds/roles.rs
@@ -6,28 +6,18 @@ use crate::{
errors::{ChorusError, ChorusResult},
instance::UserMeta,
ratelimiter::ChorusRequest,
- types::{self, RoleCreateModifySchema, RoleObject, Snowflake},
+ types::{self, RoleCreateModifySchema, RoleObject, RolePositionUpdateSchema, Snowflake},
};
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.
- ///
- /// # Errors
- ///
- /// Returns a [`ChorusLibError`] if the request fails or if the response is invalid.
+ /// # Reference
+ /// See
pub async fn get_all(
user: &mut UserMeta,
guild_id: Snowflake,
- ) -> ChorusResult