From 83d4ffc4e84397df89a1a2d40a4ac4d9ebc08d18 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] 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();