Moar docs

src/api/guilds/guilds.rs

@@ -114,20 +114,7 @@ impl Guild {
 }
 
 impl Channel {
-    /// Sends a request to create a new channel in a guild.
+    /// Creates 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.
     pub async fn create(
         user: &mut UserMeta,
         guild_id: Snowflake,

src/api/guilds/member.rs

@@ -9,17 +9,7 @@ use crate::{
 };
 
 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 [`ChorusResult`] containing a [`GuildMember`] if the request succeeds.
     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,

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
+    /// Returns Ok(None) if the guild has no roles.
-    ///
-    /// * `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.
     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.
+    /// Updates the position of a role in a given 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.
     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,

src/api/invites/mod.rs

@@ -7,9 +7,11 @@ use crate::ratelimiter::ChorusRequest;
 use crate::types::{CreateChannelInviteSchema, GuildInvite, Invite, Snowflake};
 
 impl UserMeta {
-    /// # Arguments
+    /// Accepts an invite to a guild, group DM, or DM.
-    /// - invite_code: The invite code to accept the invite for.
+    ///
-    /// - session_id: The session ID that is accepting the invite, required for guest invites.
+    /// 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 <https://discord-userdoccers.vercel.app/resources/invite#accept-invite>
@@ -35,7 +37,13 @@ impl UserMeta {
         }
         request.deserialize_response::<Invite>(self).await
     }
+
+    /// Creates a new friend invite.
+    ///
     /// Note: Spacebar does not yet implement this endpoint.
+    ///
+    /// # Reference:
+    /// Read <https://discord-userdoccers.vercel.app/resources/invite#create-user-invite>
     pub async fn create_user_invite(&mut self, code: Option<&str>) -> ChorusResult<Invite> {
         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,

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<GeneralConfiguration> {
         let endpoint_url = self.urls.api.clone() + "/policies/instance/";
         let request = match self.client.get(&endpoint_url).send().await {

src/api/users/guilds.rs

@@ -7,11 +7,11 @@ use crate::ratelimiter::ChorusRequest;
 use crate::types::Snowflake;
 
 impl UserMeta {
-    /// # Arguments:
+    /// Leaves a given guild.
-    /// - lurking: Whether the user is lurking in the guild
     ///
     /// # Reference:
     /// Read <https://discord-userdoccers.vercel.app/resources/guild#leave-guild>
+    // TODO: Docs: What is lurking here?
     pub async fn leave_guild(&mut self, guild_id: &Snowflake, lurking: bool) -> ChorusResult<()> {
         ChorusRequest {
             request: Client::new()

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
+    /// # Reference
-    ///
+    /// See <https://luna.gitlab.io/discord-unofficial-docs/relationships.html#get-users-peer-id-relationships>
-    /// * `user_id` - ID of the user to retrieve the mutual relationships with.
-    ///
-    /// # Returns
-    /// This function returns a [`ChorusResult<Vec<PublicUser>>`].
     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
+    /// # Reference
-    /// This function returns a [`ChorusResult<Vec<types::Relationship>>`].
+    /// See <https://luna.gitlab.io/discord-unofficial-docs/relationships.html#get-users-me-relationships>
     pub async fn get_relationships(&mut self) -> ChorusResult<Vec<types::Relationship>> {
         let url = format!(
             "{}/users/@me/relationships/",
@@ -58,12 +54,8 @@ impl UserMeta {
 
     /// Sends a friend request to a user.
     ///
-    /// # Arguments
+    /// # Reference
-    ///
+    /// See <https://luna.gitlab.io/discord-unofficial-docs/relationships.html#post-users-me-relationships>
-    /// * `schema` - A [`FriendRequestSendSchema`] struct that holds the information about the friend request to be sent.
-    ///
-    /// # Returns
-    /// This function returns a [`ChorusResult`].
     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
+    /// Can be used to unfriend users, accept or send friend requests and block or unblock users.
-    ///
-    /// * `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`].
     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
+    /// # Reference
-    ///
+    /// See <https://luna.gitlab.io/discord-unofficial-docs/relationships.html#delete-users-me-relationships-peer-id>
-    /// * `user_id` - ID of the user to remove the relationship with.
-    ///
-    /// # Returns
-    /// This function returns a [`ChorusResult`].
     pub async fn remove_relationship(&mut self, user_id: Snowflake) -> ChorusResult<()> {
         let url = format!(
             "{}/users/@me/relationships/{}/",

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
+    /// # Notes
-    ///
+    /// This function is a wrapper around [`User::get`].
-    /// * `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.
     pub async fn get(user: &mut UserMeta, id: Option<&String>) -> ChorusResult<User> {
         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`.
+    /// Modifies the current user's representation. (See [`User`])
-    ///
-    /// # 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.
     pub async fn modify(&mut self, modify_schema: UserModifySchema) -> ChorusResult<User> {
         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.
+    /// 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.
     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<User> {
         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.
+    /// Gets a user by id, or if the id is None, gets the current user.
-    // # Arguments
+    ///
-    // * `token` - A valid access token for the API.
+    /// # Notes
-    // * `id` - The id of the user that will be retrieved. If this is None, the current user will be retrieved.
+    /// This function is a wrapper around [`User::get`].
-    // # Errors
-    // * [`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<User> {
         let mut user = UserMeta::shell(Rc::new(RefCell::new(self.clone())), token).await;
         let result = User::get(&mut user, id).await;

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<RefCell<Instance>>,
     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<RefCell<Instance>>,
         token: String,

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
+/// A URLBundle bundles together the API-, Gateway- and CDN-URLs of a Spacebar instance.
-/// 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
+    /// Parses a URL using the Url library and formats it in a standardized way.
-    /// way. If no protocol is given, HTTP (not HTTPS) is assumed.
+    /// If no protocol is given, HTTP (not HTTPS) is assumed.
-    /// # Example:
+    ///
+    /// # Examples:
     /// ```rs
     /// let url = parse_url("localhost:3000");
     /// ```

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