From 6873fb12acc601521c2f2b6e2800d1538e6950d2 Mon Sep 17 00:00:00 2001
From: Still Hsu <341464@gmail.com>
Date: Sat, 23 Jun 2018 10:47:54 +0800
Subject: [PATCH] Add clarification in the emoji article

* Emphasize that normal emoji string will not translate to its Unicode representation.
* Clean up or add some of the samples featured in the article.
+ Add emoji/emote declaration section for clarification.
+ Add WebSocket emote sample.
- Remove inconsistent styling ('wacky memes' proves to be too out of place).
---
 docs/guides/emoji/emoji.md                    | 33 +++++++++++++------
 docs/guides/emoji/samples/emoji-sample.cs     |  8 ++---
 docs/guides/emoji/samples/emote-sample.cs     |  7 ++++
 .../emoji/samples/socket-emote-sample.cs      | 11 +++++++
 4 files changed, 45 insertions(+), 14 deletions(-)
 create mode 100644 docs/guides/emoji/samples/emote-sample.cs
 create mode 100644 docs/guides/emoji/samples/socket-emote-sample.cs

diff --git a/docs/guides/emoji/emoji.md b/docs/guides/emoji/emoji.md
index 2c045b1b1..5565e3875 100644
--- a/docs/guides/emoji/emoji.md
+++ b/docs/guides/emoji/emoji.md
@@ -14,10 +14,9 @@ depending on the type of emoji, they are sent in an entirely
 different format.
 
 What does this all mean? It means that you should know that by
-doing something like
-`channel.SendMessageAsync(“Discord.Net is :ok_hand:”);`, it will not
-translate to `Discord.Net is 👌`, rather, it will be not be
-translated at all, and will simply send `Discord.Net is :ok_hand:`.
+sending a string like `“Discord.Net is :ok_hand:”` will **NOT**
+translate to `Discord.Net is 👌`; rather, it will be treated as-is,
+like `Discord.Net is :ok_hand:`.
 
 ## Emoji
 
@@ -44,7 +43,14 @@ form; this can be obtained in several different ways.
     IDE sometimes do not render the Unicode emoji correctly.
     ![Fileformat Emoji Source Code](images/fileformat-emoji-src.png)
 
-Your method relating to an emoji should now look something like this:
+### Emoji Declaration
+
+After obtaining the Unicode representation of the emoji, you may
+create the @Discord.Emoji object by passing the string into its
+constructor (e.g. `new Emoji("👌");` or `new Emoji("\uD83D\uDC4C");`).
+
+Your method of declaring an @Discord.Emoji should look similar to
+this:
 
 [!code-csharp[Emoji Sample](samples/emoji-sample.cs)]
 
@@ -54,8 +60,7 @@ Your method relating to an emoji should now look something like this:
 
 The meat of the debate is here; what is an emote and how does it
 differ from an emoji? An emote refers to a **custom emoji**
-created on Discord, like those wacky meme emojis you have seen all
-over the platform.
+created on Discord.
 
 The underlying structure of an emote also differs drastically; an
 emote looks sort-of like a mention on Discord. It consists of two
@@ -67,13 +72,21 @@ As you can see, emote uses a completely different format. To obtain
 the raw string as shown above for your emote, you would need to
 escape the emote using the escape character `\` in chat somewhere.
 
-After obtaining the raw emote string, you could use
-@Discord.Emote.Parse* or @Discord.Emote.TryParse* to create an
-@Discord.Emote to be used.
+### Emote Declaration
+
+After obtaining the raw emote string, you would need to use
+@Discord.Emote.Parse* or @Discord.Emote.TryParse* to create a valid
+emote object.
+
+Your method of declaring an @Discord.Emote should look similar to
+this:
+
+[!code[Emote Sample](samples/emote-sample.cs)]
 
 > [!TIP]
 > For WebSocket users, you may also consider fetching the Emote
 > via the @Discord.WebSocket.SocketGuild.Emotes collection.
+> [!code-csharp[Socket emote sample](samples/socket-emote-sample.cs)]
 
 ## Additional Information
 
diff --git a/docs/guides/emoji/samples/emoji-sample.cs b/docs/guides/emoji/samples/emoji-sample.cs
index b02fb8935..a36e6f70a 100644
--- a/docs/guides/emoji/samples/emoji-sample.cs
+++ b/docs/guides/emoji/samples/emoji-sample.cs
@@ -1,6 +1,6 @@
-public async Task SendEmojiAndEmote(ISocketMessageChannel channel)
+public async Task ReactAsync(SocketUserMessage userMsg)
 {
-    await channel.SendMessageAsync("\uD83D\uDC4C");
-    // or
-    // await channel.SendMessageAsync("👌");
+    // equivalent to "👌"
+    var emoji = new Emoji("\uD83D\uDC4C");
+    await userMsg.AddReactionAsync(emoji);
 }
\ No newline at end of file
diff --git a/docs/guides/emoji/samples/emote-sample.cs b/docs/guides/emoji/samples/emote-sample.cs
new file mode 100644
index 000000000..b05ecc269
--- /dev/null
+++ b/docs/guides/emoji/samples/emote-sample.cs
@@ -0,0 +1,7 @@
+public async Task ReactWithEmoteAsync(SocketUserMessage userMsg, string escapedEmote)
+{
+    if (Emote.TryParse(escapedEmote, out var emote))
+    {
+        await userMsg.AddReactionAsync(emote);
+    }
+}
\ No newline at end of file
diff --git a/docs/guides/emoji/samples/socket-emote-sample.cs b/docs/guides/emoji/samples/socket-emote-sample.cs
new file mode 100644
index 000000000..397111512
--- /dev/null
+++ b/docs/guides/emoji/samples/socket-emote-sample.cs
@@ -0,0 +1,11 @@
+private readonly DiscordSocketClient _client;
+
+public async Task ReactAsync(SocketUserMessage userMsg, string emoteName)
+{
+    var emote = _client.Guilds
+            .SelectMany(x => x.Emotes)
+            .FirstOrDefault(x => x.Name.IndexOf(
+                emoteName, StringComparison.OrdinalIgnoreCase) != -1);
+    if (emote == null) return;
+    await userMsg.AddReactionAsync(emote);
+}
\ No newline at end of file