Move IUser and IGuildChannel examples

src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs

@@ -101,22 +101,9 @@ namespace Discord
         ///     <see cref="IGuild.GetChannelAsync"/>. Next, it checks if an overwrite had already been set via 
         ///     <see cref="GetPermissionOverwrite(Discord.IRole)"/>; if not, it denies the role from sending any
         ///     messages to the channel.
-        ///     <code lang="cs">
-        ///     // Fetches the role and channels
-        ///     var role = guild.GetRole(339805618376540160);
-        ///     var channel = await guild.GetChannelAsync(233937283911385098);
-        /// 
-        ///     // If either the of the object does not exist, bail
-        ///     if (role == null || channel == null) return;
-        ///
-        ///     // Fetches the previous overwrite and bail if one is found
-        ///     var previousOverwrite = channel.GetPermissionOverwrite(role);
-        ///     if (previousOverwrite.HasValue) return;
-        /// 
-        ///     // Creates a new OverwritePermissions with send message set to deny and pass it into the method
-        ///     await channel.AddPermissionOverwriteAsync(role,
-        ///         new OverwritePermissions(sendMessage: PermValue.Deny));
-        ///     </code>
+        ///     <code lang="cs" 
+        ///           source="../Discord.Net.Examples/Core/Entities/Channels/IGuildChannel.Examples.cs" 
+        ///           region="AddPermissionOverwriteAsyncRole"/>
         /// </example>
         /// <param name="role">The role to add the overwrite to.</param>
         /// <param name="permissions">The overwrite to add to the role.</param>
@@ -134,22 +121,9 @@ namespace Discord
         ///     <see cref="IGuild.GetChannelAsync"/>. Next, it checks if an overwrite had already been set via 
         ///     <see cref="GetPermissionOverwrite(Discord.IUser)"/>; if not, it denies the user from sending any
         ///     messages to the channel.
-        ///     <code lang="cs">
-        ///     // Fetches the role and channels
-        ///     var user = await guild.GetUserAsync(168693960628371456);
-        ///     var channel = await guild.GetChannelAsync(233937283911385098);
-        /// 
-        ///     // If either the of the object does not exist, bail
-        ///     if (user == null || channel == null) return;
-        ///
-        ///     // Fetches the previous overwrite and bail if one is found
-        ///     var previousOverwrite = channel.GetPermissionOverwrite(user);
-        ///     if (previousOverwrite.HasValue) return;
-        /// 
-        ///     // Creates a new OverwritePermissions with send message set to deny and pass it into the method
-        ///     await channel.AddPermissionOverwriteAsync(role,
-        ///         new OverwritePermissions(sendMessage: PermValue.Deny));
-        ///     </code>
+        ///     <code lang="cs" 
+        ///           source="../Discord.Net.Examples/Core/Entities/Channels/IGuildChannel.Examples.cs" 
+        ///           region="AddPermissionOverwriteAsyncUser"/>
         /// </example>
         /// <param name="user">The user to add the overwrite to.</param>
         /// <param name="permissions">The overwrite to add to the user.</param>

src/Discord.Net.Core/Entities/Users/IUser.cs

@@ -23,10 +23,7 @@ namespace Discord
         /// <example>
         ///     The following example attempts to retrieve the user's current avatar and send it to a channel; if one is
         ///     not set, a default avatar for this user will be returned instead.
-        ///     <code language="cs">
-        ///     var userAvatarUrl = user.GetAvatarUrl() ?? user.GetDefaultAvatarUrl();
-        ///     await textChannel.SendMessageAsync(userAvatarUrl);
-        ///     </code>
+        ///     <code source="../Discord.Net.Examples/Core/Entities/Users/IUser.Examples.cs" region="GetAvatarUrl"/>
         /// </example>
         /// <param name="format">The format to return.</param>
         /// <param name="size">The size of the image to return in. This can be any power of two between 16 and 2048.
@@ -84,27 +81,18 @@ namespace Discord
         /// <remarks>
         ///     This method is used to obtain or create a channel used to send a direct message.
         ///     <note type="warning">
-        ///     In event that the current user cannot send a message to the target user, a channel can and will still be
-        ///     created by Discord. However, attempting to send a message will yield a 
-        ///     <see cref="Discord.Net.HttpException"/> with a 403 as its 
-        ///     <see cref="Discord.Net.HttpException.HttpCode"/>. There are currently no official workarounds by
-        ///     Discord.
+        ///          In event that the current user cannot send a message to the target user, a channel can and will
+        ///          still be created by Discord. However, attempting to send a message will yield a 
+        ///          <see cref="Discord.Net.HttpException"/> with a 403 as its 
+        ///          <see cref="Discord.Net.HttpException.HttpCode"/>. There are currently no official workarounds by
+        ///          Discord.
         ///     </note>
         /// </remarks>
         /// <example>
         ///     The following example attempts to send a direct message to the target user and logs the incident should
         ///     it fail.
-        ///     <code language="cs">
-        ///     var channel = await user.GetOrCreateDMChannelAsync();
-        ///     try
-        ///     {
-        ///         await channel.SendMessageAsync("Awesome stuff!");
-        ///     }
-        ///     catch (Discord.Net.HttpException ex) when (ex.HttpCode == 403)
-        ///     {
-        ///         Console.WriteLine($"Boo, I cannot message {user}");
-        ///     }
-        ///     </code>
+        ///     <code source="../Discord.Net.Examples/Core/Entities/Users/IUser.Examples.cs" 
+        ///           region="GetOrCreateDMChannelAsync"/>
         /// </example>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>

src/Discord.Net.Examples/Core/Entities/Channels/IGuildChannel.Examples.cs

@@ -0,0 +1,31 @@
+#region AddPermissionOverwriteAsyncRole
+public async Task MuteRoleAsync(IRole role, IGuildChannel channel)
+{
+    if (role == null) throw new ArgumentNullException(nameof(role));
+    if (channel == null) throw new ArgumentNullException(nameof(channel));
+
+    // Fetches the previous overwrite and bail if one is found
+    var previousOverwrite = channel.GetPermissionOverwrite(role);
+    if (previousOverwrite.HasValue && previousOverwrite.Value.SendMessages == PermValue.Deny)
+        throw new InvalidOperationException($"Role {role.Name} had already been muted in this channel.");
+
+    // Creates a new OverwritePermissions with send message set to deny and pass it into the method
+    await channel.AddPermissionOverwriteAsync(role, new OverwritePermissions(sendMessages: PermValue.Deny));
+}
+#endregion
+
+#region AddPermissionOverwriteAsyncUser
+public async Task MuteUserAsync(IGuildUser user, IGuildChannel channel)
+{
+    if (role == null) throw new ArgumentNullException(nameof(user));
+    if (channel == null) throw new ArgumentNullException(nameof(channel));
+
+    // Fetches the previous overwrite and bail if one is found
+    var previousOverwrite = channel.GetPermissionOverwrite(user);
+    if (previousOverwrite.HasValue && previousOverwrite.Value.SendMessages == PermValue.Deny)
+        throw new InvalidOperationException($"User {user.Name} had already been muted in this channel.");
+
+    // Creates a new OverwritePermissions with send message set to deny and pass it into the method
+    await channel.AddPermissionOverwriteAsync(user, new OverwritePermissions(sendMessages: PermValue.Deny));
+}
+#endregion

src/Discord.Net.Examples/Core/Entities/Users/IUser.Examples.cs

@@ -0,0 +1,22 @@
+#region GetAvatarUrl
+public async Task GetAvatarAsync(IUser user)
+{
+    var userAvatarUrl = user.GetAvatarUrl() ?? user.GetDefaultAvatarUrl();
+    await textChannel.SendMessageAsync(userAvatarUrl);
+}
+#endregion
+
+#region GetOrCreateDMChannelAsync
+public async Task MessageUserAsync(IUser user)
+{
+    var channel = await user.GetOrCreateDMChannelAsync();
+    try
+    {
+        await channel.SendMessageAsync("Awesome stuff!");
+    }
+    catch (Discord.Net.HttpException ex) when (ex.HttpCode == 403)
+    {
+        Console.WriteLine($"Boo, I cannot message {user}");
+    }
+}
+#endregion