Add more examples and improve some others

Add examples to some functions, and update some of the old examples to
use the `?` operator instead of unwrapping.

1 files changed, 141 insertions, 25 deletions

diff --git a/src/client/context.rs b/src/client/context.rs
index 22216b1..9cb76b7 100644
--- a/src/client/context.rs
+++ b/src/client/context.rs
@@ -74,8 +74,16 @@ impl Context {
     ///
     /// Change the current user's username:
     ///
-    /// ```rust,ignore
-    /// context.edit_profile(|p| p.username("Hakase"));
+    /// ```rust,no_run
+    /// # use serenity::Client;
+    /// #
+    /// # let mut client = Client::login("");
+    /// #
+    /// # client.on_message(|ctx, msg| {
+    /// #     if msg.content == "!changename" {
+    /// ctx.edit_profile(|p| p.username("Hakase"));
+    /// #     }
+    /// # });
     /// ```
     #[cfg(feature="builder")]
     pub fn edit_profile<F: FnOnce(EditProfile) -> EditProfile>(&self, f: F) -> Result<CurrentUser> {
@@ -105,7 +113,22 @@ impl Context {
     }
 
     /// Sets the current user as being [`Online`]. This maintains the current
-    /// game and `afk` setting.
+    /// game.
+    ///
+    /// # Examples
+    ///
+    /// Set the current user to being online on the shard:
+    ///
+    /// ```rust,no_run
+    /// # use serenity::Client;
+    /// #
+    /// # let mut client = Client::login("");
+    /// client.on_message(|ctx, msg| {
+    ///     if msg.content == "!online" {
+    ///         ctx.online();
+    ///     }
+    /// });
+    /// ```
     ///
     /// [`Online`]: ../model/enum.OnlineStatus.html#variant.Online
     pub fn online(&self) {
@@ -113,7 +136,22 @@ impl Context {
     }
 
     /// Sets the current user as being [`Idle`]. This maintains the current
-    /// game and `afk` setting.
+    /// game.
+    ///
+    /// # Examples
+    ///
+    /// Set the current user to being idle on the shard:
+    ///
+    /// ```rust,no_run
+    /// # use serenity::Client;
+    /// #
+    /// # let mut client = Client::login("");
+    /// client.on_message(|ctx, msg| {
+    ///     if msg.content == "!idle" {
+    ///         ctx.idle();
+    ///     }
+    /// });
+    /// ```
     ///
     /// [`Idle`]: ../model/enum.OnlineStatus.html#variant.Idle
     pub fn idle(&self) {
@@ -121,7 +159,22 @@ impl Context {
     }
 
     /// Sets the current user as being [`DoNotDisturb`]. This maintains the
-    /// current game and `afk` setting.
+    /// current game.
+    ///
+    /// # Examples
+    ///
+    /// Set the current user to being Do Not Disturb on the shard:
+    ///
+    /// ```rust,no_run
+    /// # use serenity::Client;
+    /// #
+    /// # let mut client = Client::login("");
+    /// client.on_message(|ctx, msg| {
+    ///     if msg.content == "!dnd" {
+    ///         ctx.dnd();
+    ///     }
+    /// });
+    /// ```
     ///
     /// [`DoNotDisturb`]: ../model/enum.OnlineStatus.html#variant.DoNotDisturb
     pub fn dnd(&self) {
@@ -129,18 +182,47 @@ impl Context {
     }
 
     /// Sets the current user as being [`Invisible`]. This maintains the current
-    /// game and `afk` setting.
+    /// game.
     ///
+    /// # Examples
+    ///
+    /// Set the current user to being invisible on the shard when an
+    /// [`Event::Ready`] is received:
+    ///
+    /// ```rust,no_run
+    /// # use serenity::Client;
+    /// #
+    /// # let mut client = Client::login("");
+    /// client.on_ready(|ctx, _| {
+    ///     ctx.invisible();
+    /// });
+    /// ```
+    ///
+    /// [`Event::Ready`]: ../model/event/enum.Event.html#variant.Ready
     /// [`Invisible`]: ../model/enum.OnlineStatus.html#variant.Invisible
     pub fn invisible(&self) {
         self.shard.lock().unwrap().set_status(OnlineStatus::Invisible);
     }
 
-    /// "Resets" the current user's presence, by setting the game to `None`,
-    /// the online status to [`Online`], and `afk` to `false`.
+    /// "Resets" the current user's presence, by setting the game to `None` and
+    /// the online status to [`Online`].
     ///
     /// Use [`set_presence`] for fine-grained control over individual details.
     ///
+    /// # Examples
+    ///
+    /// Reset the presence when an [`Event::Resumed`] is received:
+    ///
+    /// ```rust,no_run
+    /// # use serenity::Client;
+    /// #
+    /// # let mut client = Client::login("");
+    /// client.on_resume(|ctx, _| {
+    ///     ctx.reset_presence();
+    /// });
+    /// ```
+    ///
+    /// [`Event::Resumed`]: ../model/event/enum.Event.html#variant.Resumed
     /// [`Online`]: ../model/enum.OnlineStatus.html#variant.Online
     /// [`set_presence`]: #method.set_presence
     pub fn reset_presence(&self) {
@@ -149,19 +231,29 @@ impl Context {
             .set_presence(None, OnlineStatus::Online, false)
     }
 
-    /// Sets the current game, defaulting to an online status of [`Online`], and
-    /// setting `afk` to `false`.
+    /// Sets the current game, defaulting to an online status of [`Online`].
     ///
     /// # Examples
     ///
-    /// Set the current user as playing "Heroes of the Storm":
+    /// Create a command named `~setgame` that accepts a name of a game to be
+    /// playing:
     ///
-    /// ```rust,ignore
+    /// ```rust,no_run
+    /// # use serenity::Client;
+    /// #
+    /// # let mut client = Client::login("");
+    /// #
     /// use serenity::model::Game;
     ///
-    /// // assuming you are in a context
+    /// client.on_message(|ctx, msg| {
+    ///     let args = msg.content.splitn(2, ' ').collect::<Vec<&str>>();
+    ///
+    ///     if args.len() < 2 || *unsafe { args.get_unchecked(0) } != "~setgame" {
+    ///         return;
+    ///     }
     ///
-    /// context.set_game(Game::playing("Heroes of the Storm"));
+    ///     ctx.set_game(Game::playing(*unsafe { args.get_unchecked(1) }));
+    /// });
     /// ```
     ///
     /// [`Online`]: ../model/enum.OnlineStatus.html#variant.Online
@@ -180,6 +272,21 @@ impl Context {
     ///
     /// **Note**: Maximum length is 128.
     ///
+    /// # Examples
+    ///
+    /// When an [`Event::Ready`] is received, set the game name to `"test"`:
+    ///
+    /// ```rust,no_run
+    /// # use serenity::Client;
+    /// #
+    /// # let mut client = Client::login("");
+    /// #
+    /// client.on_ready(|ctx, _| {
+    ///     ctx.set_game_name("test");
+    /// });
+    /// ```
+    ///
+    /// [`Event::Ready`]: ../model/event/enum.Event.html#variant.Ready
     /// [`GameType`]: ../model/enum.GameType.html
     /// [`Online`]: ../model/enum.OnlineStatus.html#variant.Online
     /// [`OnlineStatus`]: ../model/enum.OnlineStatus.html
@@ -202,29 +309,38 @@ impl Context {
     ///
     /// # Examples
     ///
-    /// Setting the current user as having no game, being [`Idle`],
-    /// and setting `afk` to `true`:
+    /// Setting the current user as having no game and being [`Idle`]:
     ///
-    /// ```rust,ignore
+    /// ```rust,no_run
+    /// # use serenity::Client;
+    /// #
+    /// # let mut client = Client::login("");
+    /// #
+    /// # client.on_ready(|ctx, _| {
+    /// #
     /// use serenity::model::OnlineStatus;
     ///
-    /// // assuming you are in a context
-    ///
-    /// context.set_game(None, OnlineStatus::Idle, true);
+    /// ctx.set_presence(None, OnlineStatus::Idle, false);
+    /// # });
     /// ```
     ///
-    /// Setting the current user as playing "Heroes of the Storm", being
-    /// [`DoNotDisturb`], and setting `afk` to `false`:
+    /// Setting the current user as playing `"Heroes of the Storm"`, while being
+    /// [`DoNotDisturb`]:
     ///
     /// ```rust,ignore
+    /// # use serenity::Client;
+    /// #
+    /// # let mut client = Client::login("");
+    /// #
+    /// # client.on_ready(|ctx, _| {
+    /// #
     /// use serenity::model::{Game, OnlineStatus};
     ///
-    /// // assuming you are in a context
-    ///
     /// let game = Game::playing("Heroes of the Storm");
     /// let status = OnlineStatus::DoNotDisturb;
     ///
-    /// context.set_game(Some(game), status, false);
+    /// context.set_presence(Some(game), status, false);
+    /// # });
     /// ```
     ///
     /// [`DoNotDisturb`]: ../model/enum.OnlineStatus.html#variant.DoNotDisturb