From 5465466e18eec8a628d41a7bca4e002c2e26836c Mon Sep 17 00:00:00 2001 From: jamesbt365 Date: Sat, 25 May 2024 18:03:48 +0100 Subject: [PATCH] Document builder execute --- src/builder/edit_onboarding/mod.rs | 41 ++++++++++++------- .../prompt_option_structure.rs | 11 +++-- .../edit_onboarding/prompt_structure.rs | 2 +- src/http/client.rs | 7 +++- src/model/guild/onboarding.rs | 22 +++++----- 5 files changed, 49 insertions(+), 34 deletions(-) diff --git a/src/builder/edit_onboarding/mod.rs b/src/builder/edit_onboarding/mod.rs index 2d2b4fb5371..6cc6807f743 100644 --- a/src/builder/edit_onboarding/mod.rs +++ b/src/builder/edit_onboarding/mod.rs @@ -1,19 +1,17 @@ #[cfg(feature = "http")] use super::Builder; - +#[cfg(feature = "http")] +use crate::http::CacheHttp; +#[cfg(feature = "http")] +use crate::internal::prelude::*; +#[cfg(feature = "http")] +use crate::model::guild::Onboarding; use crate::model::guild::OnboardingMode; use crate::model::id::ChannelId; - #[cfg(feature = "http")] use crate::model::id::GuildId; #[cfg(feature = "http")] use crate::model::Permissions; -#[cfg(feature = "http")] -use crate::http::CacheHttp; -#[cfg(feature = "http")] -use crate::model::guild::Onboarding; -#[cfg(feature = "http")] -use crate::internal::prelude::*; mod prompt_option_structure; mod prompt_structure; @@ -82,7 +80,7 @@ impl<'a> EditOnboarding<'a, NeedsPrompts> { Self::default() } - + /// The onboarding prompts that users can select the options of. pub fn prompts( self, prompts: Vec>, @@ -101,11 +99,10 @@ impl<'a> EditOnboarding<'a, NeedsPrompts> { impl<'a> EditOnboarding<'a, NeedsChannels> { /// The list of default channels the user will have regardless of the answers given. - /// + /// /// There are restrictions that apply only when onboarding is enabled, but these vary depending /// on the current [Self::mode]. - /// - /// + /// /// If the default mode is set, you must provide at least 7 channels, 5 of which must allow /// @everyone to read and send messages. if advanced is set, the restrictions apply across the /// default channels and the [Self::prompts], provided that they supply the remaining required @@ -143,7 +140,7 @@ impl<'a> EditOnboarding<'a, NeedsEnabled> { impl<'a> EditOnboarding<'a, NeedsMode> { /// The current onboarding mode that controls where the readable channels are set. - /// + /// /// If the default mode is set, you must provide at least 7 channels, 5 of which must allow /// @everyone to read and send messages. if advanced is set, the restrictions apply across the /// default channels and the [Self::prompts], provided that they supply the remaining required @@ -169,20 +166,34 @@ impl<'a, Stage: Sealed> EditOnboarding<'a, Stage> { } } - #[cfg(feature = "http")] #[async_trait::async_trait] impl<'a> Builder for EditOnboarding<'a, Ready> { type Context<'ctx> = GuildId; type Built = Onboarding; + /// Sets [`Onboarding`] in the guild. + /// + /// **Note**: Requires the [Manage Roles] and [Manage Guild] permissions. + /// + /// # Errors + /// + /// If the `cache` is enabled, returns a [`ModelError::InvalidPermissions`] if the current user + /// lacks permission. Otherwise returns [`Error::Http`], as well as if invalid data is given. + /// + /// [Manage Roles]: Permissions::MANAGE_ROLES + /// [Manage Guild]: Permissions::MANAGE_GUILD async fn execute( mut self, cache_http: impl CacheHttp, ctx: Self::Context<'_>, ) -> Result { #[cfg(feature = "cache")] - crate::utils::user_has_guild_perms(&cache_http, ctx, Permissions::MANAGE_GUILD | Permissions::MANAGE_ROLES)?; + crate::utils::user_has_guild_perms( + &cache_http, + ctx, + Permissions::MANAGE_GUILD | Permissions::MANAGE_ROLES, + )?; cache_http.http().set_guild_onboarding(ctx, &self, self.audit_log_reason).await } diff --git a/src/builder/edit_onboarding/prompt_option_structure.rs b/src/builder/edit_onboarding/prompt_option_structure.rs index 86b60aabf01..c893fe3160b 100644 --- a/src/builder/edit_onboarding/prompt_option_structure.rs +++ b/src/builder/edit_onboarding/prompt_option_structure.rs @@ -33,7 +33,6 @@ pub struct CreatePromptOption { _stage: Stage, } - impl Default for CreatePromptOption { /// See the documentation of [`Self::new`]. fn default() -> Self { @@ -57,7 +56,7 @@ impl CreatePromptOption { } /// The channels that become visible when selecting this option. - /// + /// /// At least one channel or role must be selected or the option will not be valid. pub fn channels(self, channel_ids: Vec) -> CreatePromptOption { CreatePromptOption { @@ -74,7 +73,7 @@ impl CreatePromptOption { impl CreatePromptOption { /// The roles granted from selecting this option. - /// + /// /// At least one channel or role must be selected or the option will not be valid. pub fn roles(self, role_ids: Vec) -> CreatePromptOption { CreatePromptOption { @@ -117,7 +116,7 @@ impl CreatePromptOption { } } -use serde::ser::{Serialize, Serializer, SerializeStruct}; +use serde::ser::{Serialize, SerializeStruct, Serializer}; // This implementation allows us to put the emoji fields on without storing duplicate values. impl Serialize for CreatePromptOption { @@ -142,10 +141,10 @@ impl Serialize for CreatePromptOption { state.serialize_field("emoji_animated", animated)?; state.serialize_field("emoji_id", id)?; state.serialize_field("emoji_name", name)?; - } + }, ReactionType::Unicode(name) => { state.serialize_field("emoji_name", name)?; - } + }, } } diff --git a/src/builder/edit_onboarding/prompt_structure.rs b/src/builder/edit_onboarding/prompt_structure.rs index ed6149d8d38..9e1cf52e68a 100644 --- a/src/builder/edit_onboarding/prompt_structure.rs +++ b/src/builder/edit_onboarding/prompt_structure.rs @@ -94,7 +94,7 @@ impl CreateOnboardingPrompt { impl CreateOnboardingPrompt { /// The options users can select for the prompt. - /// + /// /// Each option must provide at least one role or channel. pub fn options( self, diff --git a/src/http/client.rs b/src/http/client.rs index 350d36d5a99..044ec39c891 100644 --- a/src/http/client.rs +++ b/src/http/client.rs @@ -4687,7 +4687,12 @@ impl Http { } /// Sets the onboarding configuration for the guild. - pub async fn set_guild_onboarding(&self, guild_id: GuildId, map: &impl serde::Serialize, audit_log_reason: Option<&str>) -> Result { + pub async fn set_guild_onboarding( + &self, + guild_id: GuildId, + map: &impl serde::Serialize, + audit_log_reason: Option<&str>, + ) -> Result { let body = to_vec(map)?; self.fire(Request { diff --git a/src/model/guild/onboarding.rs b/src/model/guild/onboarding.rs index dec21a39882..d35511c65d3 100644 --- a/src/model/guild/onboarding.rs +++ b/src/model/guild/onboarding.rs @@ -1,7 +1,7 @@ -use crate::all::ReactionType; use serde::{Deserialize, Deserializer}; -use crate::model::id::{ChannelId, GenericId, GuildId, RoleId, EmojiId}; +use crate::all::ReactionType; +use crate::model::id::{ChannelId, EmojiId, GenericId, GuildId, RoleId}; /// Onboarding information for a [`Guild`]. /// @@ -15,7 +15,7 @@ pub struct Onboarding { pub guild_id: GuildId, /// A list of prompts associated with the onboarding process. pub prompts: Vec, - /// If onboarding is enabled, these channels will be visible by the user regardless of what + /// If onboarding is enabled, these channels will be visible by the user regardless of what /// they select in onboarding. pub default_channel_ids: Vec, /// Controls if onboarding is enabled, if onboarding is disabled, onboarding requirements are @@ -26,9 +26,9 @@ pub struct Onboarding { } /// An onboarding prompt, otherwise known as a question. -/// +/// /// At least one option is required, and there could be up to 50 options. -/// +/// /// [Discord docs](https://discord.com/developers/docs/resources/guild#guild-onboarding-object). #[derive(Debug, Clone, Deserialize, Serialize)] #[non_exhaustive] @@ -63,9 +63,9 @@ enum_number! { } /// An option, otherwise known as an answer, for an onboarding prompt. -/// +/// /// An answer must provide at least 1 channel or role to be visible. -/// +/// /// [Discord docs](https://discord.com/developers/docs/resources/guild#guild-onboarding-object-prompt-option-structure). #[derive(Debug, Clone, Deserialize, Serialize)] #[non_exhaustive] @@ -88,9 +88,9 @@ pub struct OnboardingPromptOption { enum_number! { /// Defines the criteria used to satisfy Onboarding constraints that are required for enabling. - /// - /// Currently only controls what channels count towards the constraints for enabling. - /// + /// + /// Currently only controls what channels count towards the constraints for enabling. + /// /// [Discord docs](https://discord.com/developers/docs/resources/guild#guild-onboarding-object-onboarding-mode). #[derive(Default, Debug, Clone, Deserialize, Serialize)] #[serde(from = "u8", into = "u8")] @@ -130,4 +130,4 @@ where (None, Some(name)) => Some(ReactionType::Unicode(name)), (None, None) => return Ok(None), }) -} \ No newline at end of file +}