fix: refactored changes discussed in PR

Author: foxbot

src/Discord.Net/Discord.Net.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <TargetFramework>netstandard2.0</TargetFramework>
-    <LangVersion>7.1</LangVersion>
+    <LangVersion>7.3</LangVersion>
   </PropertyGroup>
 
   <ItemGroup>

src/Discord.Net/Entities/Emotes/IEmote.cs

@@ -1,7 +1,19 @@
 namespace Discord
 {
-    public interface IEmote : IMentionable // TODO: Is `Mention` the correct verbage here?
+    /// <summary>
+    ///     An emote which may be used as a reaction or embedded in chat.
+    ///
+    ///     This includes Unicode emoji as well as unattached guild emotes.
+    /// </summary>
+    public interface IEmote : ITaggable
     {
+        /// <summary>
+        ///     The display-name of the emote.
+        /// </summary>
+        /// <remarks>
+        ///     For Unicode emoji, this is the raw value of the character, not its
+        ///     Unicode display name.
+        /// </remarks>
         string Name { get; }
     }
 }

src/Discord.Net/Entities/Emotes/IGuildEmote.cs

@@ -3,13 +3,17 @@
 
 namespace Discord
 {
+    /// <summary>
+    ///     An emote attached to a guild. This differs from an <see cref="IEmote"/> in that it contains
+    ///     information relevant to the source guild.
+    /// </summary>
     public interface IGuildEmote : IEmote, ISnowflakeEntity, IDeletable
     {
         /// <summary>
         ///     Gets whether this emoji is managed by an integration.
         /// </summary>
         /// <returns>
-        ///     A boolean that determines whether or not this emote is managed by a Twitch integration.
+        ///     A boolean that determines whether or not this emote is managed by an external integration, such as Twitch.
         /// </returns>
         bool IsManaged { get; }
         /// <summary>

src/Discord.Net/Entities/IMentionable.cs

@@ -0,0 +1,7 @@
+namespace Discord
+{
+    public interface ITaggable
+    {
+        string Tag { get; }
+    }
+}

src/Discord.Net/Entities/ITaggable.cs

@@ -8,7 +8,7 @@ namespace Discord
     /// <summary>
     ///     Represents a generic role object to be given to a guild user.
     /// </summary>
-    public interface IRole : ISnowflakeEntity, IDeletable, IMentionable, IComparable<IRole>
+    public interface IRole : ISnowflakeEntity, IDeletable, ITaggable, IComparable<IRole>
     {
         /// <summary>
         ///     Gets the guild that owns this role.

src/Discord.Net/Entities/Roles/IRole.cs

@@ -22,19 +22,22 @@ public AttachedGuildEmote(Model model, IGuild guild, IDiscordClient discord) : b
             Guild = guild;
         }
 
+        // IGuildEmote
         public bool IsManaged { get; set; }
         public bool RequireColons { get; set; }
         public IReadOnlyList<IRole> Roles { get; set; }
         public ulong? CreatorId { get; set; }
         public string Name { get; set; }
         public IGuild Guild { get; set; }
 
-        // IMentionable
-        public string Mention => EmoteUtilities.FormatGuildEmote(Id, Name);
+        // ITaggable
+        public string Tag => EmoteUtilities.FormatGuildEmote(Id, Name);
 
+        // IDeleteable
         public Task DeleteAsync()
             => Discord.Rest.DeleteGuildEmojiAsync(Guild.Id, Id);
 
+        // IGuildEmote
         public Task ModifyAsync() // TODO
         {
             throw new System.NotImplementedException();

src/Discord.Net/Models/Emotes/AttachedGuildEmote.cs

@@ -9,6 +9,6 @@ public Emoji(string name)
         }
 
         public string Name { get; set; }
-        public string Mention => Name;
+        public string Tag => Name;
     }
 }

src/Discord.Net/Models/Emotes/Emoji.cs

@@ -13,6 +13,6 @@ public Emote(ulong id, string name)
         public ulong Id { get; set; }
         public string Name { get; set; }
 
-        public string Mention => EmoteUtilities.FormatGuildEmote(Id, Name);
+        public string Tag => EmoteUtilities.FormatGuildEmote(Id, Name);
     }
 }

src/Discord.Net/Models/Emotes/Emote.cs

@@ -2,12 +2,56 @@
 
 namespace Discord
 {
+    /// <summary>
+    ///     Methods to create an <see cref="IEmote"/>.
+    /// </summary>
     public static class EmoteBuilder
     {
-        public static IEmote FromEmoji(string emoji)
+        /// <summary>
+        ///     Creates an emote from a raw unicode emoji.
+        /// </summary>
+        /// <param name="emoji">The unicode character this emoji should be created from.</param>
+        public static IEmote FromUnicodeEmoji(string emoji)
             => new Emoji(emoji);
-        public static IEmote FromMention(string mention)
-            => throw new NotImplementedException(); // TODO: emoteutil
+
+        /// <summary>
+        ///     Creates an emote from an escaped tag.
+        /// </summary>
+        /// <param name="mention">The escaped mention tag for an emote.</param>
+        /// <exception cref="ArgumentException">Throws if the passed tag was of an invalid format.</exception>
+        public static IEmote FromTag(string tag)
+        {
+            if (EmoteUtilities.TryParseGuildEmote(tag.AsSpan(), out var result))
+            {
+                var (id, name) = result;
+                return new Emote(id, name);
+            }
+            throw new ArgumentException("Passed emote tag was of an invalid format", nameof(tag));
+        }
+
+        /// <summary>
+        ///     Creates an emote from an escaped tag.
+        /// </summary>
+        /// <param name="tag">The escaped mention tag for an emote.</param>
+        /// <returns>Returns true if the emote could be created; returns false if it was of an invalid format.</returns>
+        public static bool TryFromTag(string tag, out IEmote result)
+        {
+            if (EmoteUtilities.TryParseGuildEmote(tag.AsSpan(), out var r))
+            {
+                var (id, name) = r;
+                result = new Emote(id, name);
+                return true;
+            }
+
+            result = default;
+            return false;
+        }
+
+        /// <summary>
+        ///     Creates an emote from a raw snowflake and name.
+        /// </summary>
+        /// <param name="id">The snowflake ID of the guild emote.</param>
+        /// <param name="name">The name of the guild emote.</param>
         public static IEmote FromID(ulong id, string name)
             => new Emote(id, name);
     }