Skip to content

Commit

Permalink
Clean up documentation examples (#2628)
Browse files Browse the repository at this point in the history 
This removes examples which are superfluous or otherwise useless, simplifies
existing examples down to just show the method being demonstrated, and
otherwise deleted duplicate code in every example that was not required.

This helps with larger changes to Serenity as we don't have to maintain and
keep up to date 50 small bots in-tree in form of documentation examples. It
also makes documentation clearer for users as they don't have to wade through
the same code over and over again to understand concepts.
  • Loading branch information
@GnomedDev
GnomedDev authored Nov 26, 2023
1 parent 26d3fb0 commit 49640ea
Show file tree
Hide file tree
Showing 15 changed files with 91 additions and 497 deletions.
45 changes: 0 additions & 45 deletions src/builder/create_embed.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -138,51 +138,6 @@ impl CreateEmbed {
/// let timestamp: Timestamp = "2004-06-08T16:04:23Z".parse().expect("Invalid timestamp!");
/// let embed = CreateEmbed::new().title("hello").timestamp(timestamp);
/// ```
///
/// Creating a join-log:
///
/// Note: this example isn't efficient and is for demonstrative purposes.
///
/// ```rust,no_run
/// # #[cfg(all(feature = "cache", feature = "client"))]
/// # async fn run() -> Result<(), Box<dyn std::error::Error>> {
/// use serenity::builder::{CreateEmbed, CreateEmbedAuthor, CreateMessage};
/// use serenity::model::guild::Member;
/// use serenity::model::id::GuildId;
/// use serenity::prelude::*;
///
/// struct Handler;
///
/// #[serenity::async_trait]
/// impl EventHandler for Handler {
/// async fn guild_member_addition(&self, context: Context, member: Member) {
/// let guild_id = member.guild_id;
/// if let Ok(guild) = guild_id.to_partial_guild(&context).await {
/// let channels = guild.channels(&context).await.unwrap();
///
/// let channel_search = channels.values().find(|c| c.name == "join-log");
///
/// if let Some(channel) = channel_search {
/// let icon_url = member.user.face();
/// let author = CreateEmbedAuthor::new(member.user.name).icon_url(icon_url);
/// let mut embed = CreateEmbed::new().title("Member Join").author(author);
/// if let Some(joined_at) = member.joined_at {
/// embed = embed.timestamp(joined_at);
/// }
/// let builder = CreateMessage::new().embed(embed);
/// let _ = channel.send_message(&context, builder).await;
/// }
/// }
/// }
/// }
///
/// let mut client =
/// Client::builder("token", GatewayIntents::default()).event_handler(Handler).await?;
///
/// client.start().await?;
/// # Ok(())
/// # }
/// ```
#[inline]
pub fn timestamp<T: Into<Timestamp>>(mut self, timestamp: T) -> Self {
self.0.timestamp = Some(timestamp.into());
Expand Down
102 changes: 18 additions & 84 deletions src/builder/create_invite.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,55 +15,11 @@ use crate::model::prelude::*;
/// Create an invite with a max age of 3600 seconds and 10 max uses:
///
/// ```rust,no_run
/// # #[cfg(all(feature = "cache", feature = "client"))]
/// # async fn run() -> Result<(), Box<dyn std::error::Error>> {
/// # use serenity::prelude::*;
/// # use serenity::model::prelude::*;
/// # use serenity::model::channel::Channel;
/// # use serenity::{prelude::*, model::prelude::*};
/// use serenity::builder::CreateInvite;
///
/// struct Handler;
///
/// #[serenity::async_trait]
/// impl EventHandler for Handler {
/// async fn message(&self, context: Context, msg: Message) {
/// if msg.content == "!createinvite" {
/// let channel_opt = context.cache.channel(msg.channel_id).as_deref().cloned();
/// let channel = match channel_opt {
/// Some(channel) => channel,
/// None => {
/// let _ = msg.channel_id.say(&context, "Error creating invite").await;
/// return;
/// },
/// };
///
/// let builder = CreateInvite::new().max_age(3600).max_uses(10);
/// let creation = channel.create_invite(&context, builder).await;
///
/// let invite = match creation {
/// Ok(invite) => invite,
/// Err(why) => {
/// println!("Err creating invite: {:?}", why);
/// if let Err(why) =
/// msg.channel_id.say(&context, "Error creating invite").await
/// {
/// println!("Err sending err msg: {:?}", why);
/// }
///
/// return;
/// },
/// };
///
/// let content = format!("Here's your invite: {}", invite.url());
/// let _ = msg.channel_id.say(&context, &content).await;
/// }
/// }
/// }
///
/// let mut client =
/// Client::builder("token", GatewayIntents::default()).event_handler(Handler).await?;
///
/// client.start().await?;
/// # async fn run(context: impl CacheHttp, channel: GuildChannel) -> Result<(), Box<dyn std::error::Error>> {
/// let builder = CreateInvite::new().max_age(3600).max_uses(10);
/// let creation = channel.create_invite(&context, builder).await?;
/// # Ok(())
/// # }
/// ```
Expand Down Expand Up @@ -108,17 +64,11 @@ impl<'a> CreateInvite<'a> {
/// Create an invite with a max age of `3600` seconds, or 1 hour:
///
/// ```rust,no_run
/// # #[cfg(all(feature = "cache", feature = "client"))]
/// # use serenity::client::Context;
/// # #[cfg(feature = "framework")]
/// # use serenity::framework::standard::{CommandResult, macros::command};
/// # use serenity::model::id::ChannelId;
/// # use serenity::model::prelude::*;
/// # use serenity::builder::CreateInvite;
/// # use serenity::http::CacheHttp;
/// #
/// # #[cfg(all(feature = "cache", feature = "client", feature = "framework", feature = "http"))]
/// # #[command]
/// # async fn example(context: &Context) -> CommandResult {
/// # let channel = context.cache.channel(81384788765712384).unwrap().clone();
/// # async fn example(context: impl CacheHttp, channel: GuildChannel) -> Result<(), Box<dyn std::error::Error>> {
/// let builder = CreateInvite::new().max_age(3600);
/// let invite = channel.create_invite(context, builder).await?;
/// # Ok(())
Expand All @@ -139,18 +89,14 @@ impl<'a> CreateInvite<'a> {
///
/// Create an invite with a max use limit of `5`:
///
/// Create an invite with a max age of `3600` seconds, or 1 hour:
///
/// ```rust,no_run
/// # #[cfg(all(feature = "cache", feature = "client"))]
/// # use serenity::client::Context;
/// # #[cfg(feature = "framework")]
/// # use serenity::framework::standard::{CommandResult, macros::command};
/// # use serenity::model::id::ChannelId;
/// # use serenity::model::prelude::*;
/// # use serenity::builder::CreateInvite;
/// # use serenity::http::CacheHttp;
/// #
/// # #[cfg(all(feature = "cache", feature = "client", feature = "framework", feature = "http"))]
/// # #[command]
/// # async fn example(context: &Context) -> CommandResult {
/// # let channel = context.cache.channel(81384788765712384).unwrap().clone();
/// # async fn example(context: impl CacheHttp, channel: GuildChannel) -> Result<(), Box<dyn std::error::Error>> {
/// let builder = CreateInvite::new().max_uses(5);
/// let invite = channel.create_invite(context, builder).await?;
/// # Ok(())
Expand All @@ -170,17 +116,11 @@ impl<'a> CreateInvite<'a> {
/// Create an invite which is temporary:
///
/// ```rust,no_run
/// # #[cfg(all(feature = "cache", feature = "client"))]
/// # use serenity::client::Context;
/// # #[cfg(feature = "framework")]
/// # use serenity::framework::standard::{CommandResult, macros::command};
/// # use serenity::model::id::ChannelId;
/// # use serenity::model::prelude::*;
/// # use serenity::builder::CreateInvite;
/// # use serenity::http::CacheHttp;
/// #
/// # #[cfg(all(feature = "cache", feature = "client", feature = "framework", feature = "http"))]
/// # #[command]
/// # async fn example(context: &Context) -> CommandResult {
/// # let channel = context.cache.channel(81384788765712384).unwrap().clone();
/// # async fn example(context: impl CacheHttp, channel: GuildChannel) -> Result<(), Box<dyn std::error::Error>> {
/// let builder = CreateInvite::new().temporary(true);
/// let invite = channel.create_invite(context, builder).await?;
/// # Ok(())
Expand All @@ -200,17 +140,11 @@ impl<'a> CreateInvite<'a> {
/// Create an invite which is unique:
///
/// ```rust,no_run
/// # #[cfg(all(feature = "cache", feature = "client"))]
/// # use serenity::client::Context;
/// # #[cfg(feature = "framework")]
/// # use serenity::framework::standard::{CommandResult, macros::command};
/// # use serenity::model::id::ChannelId;
/// # use serenity::model::prelude::*;
/// # use serenity::builder::CreateInvite;
/// # use serenity::http::CacheHttp;
/// #
/// # #[cfg(all(feature = "cache", feature = "client", feature = "framework", feature = "http"))]
/// # #[command]
/// # async fn example(context: &Context) -> CommandResult {
/// # let channel = context.cache.channel(81384788765712384).unwrap().clone();
/// # async fn example(context: impl CacheHttp, channel: GuildChannel) -> Result<(), Box<dyn std::error::Error>> {
/// let builder = CreateInvite::new().unique(true);
/// let invite = channel.create_invite(context, builder).await?;
/// # Ok(())
Expand Down
12 changes: 3 additions & 9 deletions src/builder/edit_message.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,15 +25,9 @@ use crate::model::prelude::*;
/// # use serenity::builder::EditMessage;
/// # use serenity::model::channel::Message;
/// # use serenity::model::id::ChannelId;
/// # #[cfg(feature = "client")]
/// # use serenity::client::Context;
/// # #[cfg(feature = "framework")]
/// # use serenity::framework::standard::{CommandResult, macros::command};
/// #
/// # #[cfg(all(feature = "model", feature = "utils", feature = "framework"))]
/// # #[command]
/// # async fn example(ctx: &Context) -> CommandResult {
/// # let mut message: Message = unimplemented!();
/// # use serenity::http::CacheHttp;
///
/// # async fn example(ctx: impl CacheHttp, mut message: Message) -> Result<(), Box<dyn std::error::Error>> {
/// let builder = EditMessage::new().content("hello");
/// message.edit(ctx, builder).await?;
/// # Ok(())
Expand Down
18 changes: 2 additions & 16 deletions src/cache/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -295,27 +295,15 @@ impl Cache {
/// ```rust,no_run
/// # use serenity::model::prelude::*;
/// # use serenity::prelude::*;
/// #
/// # #[cfg(feature = "client")]
/// # async fn run() -> Result<(), Box<dyn std::error::Error>> {
/// use std::thread;
/// use std::time::Duration;
///
/// struct Handler;
///
/// #[serenity::async_trait]
/// # #[cfg(feature = "client")]
/// impl EventHandler for Handler {
/// async fn cache_ready(&self, ctx: Context, _: Vec<GuildId>) {
/// println!("{} unknown members", ctx.cache.unknown_members());
/// }
/// }
///
/// let mut client =
/// Client::builder("token", GatewayIntents::default()).event_handler(Handler).await?;
///
/// client.start().await?;
/// # Ok(())
/// # }
/// ```
///
/// [`Shard::chunk_guild`]: crate::gateway::Shard::chunk_guild
Expand Down Expand Up @@ -657,10 +645,8 @@ impl Cache {
///
/// ```rust,no_run
/// # use serenity::client::Context;
/// # use serenity::framework::standard::{CommandResult, macros::command};
/// #
/// # #[command]
/// # async fn test(context: &Context) -> CommandResult {
/// # async fn test(context: &Context) -> Result<(), Box<dyn std::error::Error>> {
/// if let Some(user) = context.cache.user(7) {
/// println!("User with Id 7 is currently named {}", user.name);
/// }
Expand Down
Loading

0 comments on commit 49640ea

Please sign in to comment.