Add examples in message methods

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

@@ -13,6 +13,15 @@ namespace Discord
         /// <summary>
         ///     Sends a message to this message channel.
         /// </summary>
+        /// <example>
+        ///     The following example sends a message with the current system time in RFC 1123 format to the channel and
+        ///     deletes itself after 5 seconds.
+        ///     <code language="cs">
+        ///     var message = await channel.SendMessageAsync(DateTimeOffset.UtcNow.ToString("R"));
+        ///     await Task.Delay(TimeSpan.FromSeconds(5))
+        ///         .ContinueWith(x => message.DeleteAsync());
+        ///     </code>
+        /// </example>
         /// <param name="text">The message to be sent.</param>
         /// <param name="isTTS">Determines whether the message should be read aloud by Discord or not.</param>
         /// <param name="embed">The <see cref="Discord.EmbedType.Rich"/> <see cref="Embed"/> to be sent.</param>
@@ -25,12 +34,26 @@ namespace Discord
         /// <summary>
         ///     Sends a file to this message channel with an optional caption.
         /// </summary>
+        /// <example>
+        ///     The following example uploads a local file called <c>wumpus.txt</c> along with the text 
+        ///     <c>good discord boi</c> to the channel.
+        ///     <code language="cs">
+        ///     await channel.SendFileAsync("wumpus.txt", "good discord boi");
+        ///     </code>
+        /// 
+        ///     The following example uploads a local image called <c>b1nzy.jpg</c> embedded inside a rich embed to the
+        ///     channel.
+        ///     <code language="cs">
+        ///     await channel.SendFileAsync("b1nzy.jpg",
+        ///         embed: new EmbedBuilder {ImageUrl = "attachment://b1nzy.jpg"}.Build());
+        ///     </code>
+        /// </example>
         /// <remarks>
         ///     This method sends a file as if you are uploading an attachment directly from your Discord client.
         ///     <note>
-        ///         If you wish to upload an image and have it embedded in a <see cref="Discord.EmbedType.Rich"/>embed,
+        ///         If you wish to upload an image and have it embedded in a <see cref="Discord.EmbedType.Rich"/> embed,
         ///         you may upload the file and refer to the file with "attachment://filename.ext" in the
-        ///         <see cref="Discord.EmbedBuilder.ImageUrl"/>.
+        ///         <see cref="Discord.EmbedBuilder.ImageUrl"/>. See the example section for its usage.
         ///     </note>
         /// </remarks>
         /// <param name="filePath">The file path of the file.</param>
@@ -46,12 +69,20 @@ namespace Discord
         /// <summary>
         ///     Sends a file to this message channel with an optional caption.
         /// </summary>
+        /// <example>
+        ///     The following example uploads a streamed image that will be called <c>b1nzy.jpg</c> embedded inside a
+        ///     rich embed to the channel.
+        ///     <code language="cs">
+        ///     await channel.SendFileAsync(b1nzyStream, "b1nzy.jpg",
+        ///         embed: new EmbedBuilder {ImageUrl = "attachment://b1nzy.jpg"}.Build());
+        ///     </code>
+        /// </example>
         /// <remarks>
         ///     This method sends a file as if you are uploading an attachment directly from your Discord client.
         ///     <note>
-        ///         If you wish to upload an image and have it embedded in a <see cref="Discord.EmbedType.Rich"/>embed,
+        ///         If you wish to upload an image and have it embedded in a <see cref="Discord.EmbedType.Rich"/> embed,
         ///         you may upload the file and refer to the file with "attachment://filename.ext" in the
-        ///         <see cref="Discord.EmbedBuilder.ImageUrl"/>.
+        ///         <see cref="Discord.EmbedBuilder.ImageUrl"/>. See the example section for its usage.
         ///     </note>
         /// </remarks>
         /// <param name="stream">The <see cref="Stream" /> of the file to be sent.</param>

src/Discord.Net.Core/Extensions/UserExtensions.cs

@@ -29,7 +29,7 @@ namespace Discord
         /// <param name="embed">The <see cref="EmbedType.Rich"/> <see cref="Embed"/> to be sent.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     A task that represents the asynchrnonous send operation. The task result contains the sent message.
+        ///     A task that represents the asynchronous send operation. The task result contains the sent message.
         /// </returns>
         public static async Task<IUserMessage> SendMessageAsync(this IUser user,
             string text = null,
@@ -43,6 +43,14 @@ namespace Discord
         /// <summary>
         ///     Sends a file to this message channel with an optional caption.
         /// </summary>
+        /// <example>
+        ///     The following example uploads a streamed image that will be called <c>b1nzy.jpg</c> embedded inside a
+        ///     rich embed to the channel.
+        ///     <code language="cs">
+        ///     await channel.SendFileAsync(b1nzyStream, "b1nzy.jpg",
+        ///         embed: new EmbedBuilder {ImageUrl = "attachment://b1nzy.jpg"}.Build());
+        ///     </code>
+        /// </example>
         /// <remarks>
         ///     This method attempts to send an attachment as a direct-message to the user.
         ///     <note type="warning">
@@ -55,6 +63,11 @@ namespace Discord
         ///         <c>50007</c> when using this method.
         ///         </para>
         ///     </note>
+        ///     <note>
+        ///         If you wish to upload an image and have it embedded in a <see cref="Discord.EmbedType.Rich"/> embed,
+        ///         you may upload the file and refer to the file with "attachment://filename.ext" in the
+        ///         <see cref="Discord.EmbedBuilder.ImageUrl"/>. See the example section for its usage.
+        ///     </note>
         /// </remarks>
         /// <param name="user">The user to send the DM to.</param>
         /// <param name="stream">The <see cref="Stream"/> of the file to be sent.</param>
@@ -63,13 +76,9 @@ namespace Discord
         /// <param name="isTTS">Whether the message should be read aloud by Discord or not.</param>
         /// <param name="embed">The <see cref="EmbedType.Rich"/> <see cref="Embed"/> to be sent.</param>
         /// <param name="options">The options to be used when sending the request.</param>
-        /// <remarks>
-        ///     If you wish to upload an image and have it embedded in a <see cref="EmbedType.Rich"/> embed, you may
-        ///     upload the file and refer to the file with "attachment://filename.ext" in the 
-        ///     <see cref="Discord.EmbedBuilder.ImageUrl"/>.
-        /// </remarks>
         /// <returns>
-        ///     A task that represents the asynchrnonous send operation. The task result contains the sent message.
+        ///     A task that represents an asynchronous send operation for delivering the message. The task result
+        ///     contains the sent message.
         /// </returns>
         public static async Task<IUserMessage> SendFileAsync(this IUser user,
             Stream stream,
@@ -86,6 +95,20 @@ namespace Discord
         /// <summary>
         ///     Sends a file via DM with an optional caption.
         /// </summary>
+        /// <example>
+        ///     The following example uploads a local file called <c>wumpus.txt</c> along with the text 
+        ///     <c>good discord boi</c> to the channel.
+        ///     <code language="cs">
+        ///     await channel.SendFileAsync("wumpus.txt", "good discord boi");
+        ///     </code>
+        /// 
+        ///     The following example uploads a local image called <c>b1nzy.jpg</c> embedded inside a rich embed to the
+        ///     channel.
+        ///     <code language="cs">
+        ///     await channel.SendFileAsync("b1nzy.jpg",
+        ///         embed: new EmbedBuilder {ImageUrl = "attachment://b1nzy.jpg"}.Build());
+        ///     </code>
+        /// </example>
         /// <remarks>
         ///     This method attempts to send an attachment as a direct-message to the user.
         ///     <note type="warning">
@@ -98,6 +121,11 @@ namespace Discord
         ///         <c>50007</c> when using this method.
         ///         </para>
         ///     </note>
+        ///     <note>
+        ///         If you wish to upload an image and have it embedded in a <see cref="Discord.EmbedType.Rich"/> embed,
+        ///         you may upload the file and refer to the file with "attachment://filename.ext" in the
+        ///         <see cref="Discord.EmbedBuilder.ImageUrl"/>. See the example section for its usage.
+        ///     </note>
         /// </remarks>
         /// <param name="user">The user to send the DM to.</param>
         /// <param name="filePath">The file path of the file.</param>
@@ -105,13 +133,9 @@ namespace Discord
         /// <param name="isTTS">Whether the message should be read aloud by Discord or not.</param>
         /// <param name="embed">The <see cref="EmbedType.Rich"/> <see cref="Embed"/> to be sent.</param>
         /// <param name="options">The options to be used when sending the request.</param>
-        /// <remarks>
-        ///     If you wish to upload an image and have it embedded in a <see cref="EmbedType.Rich"/> embed, you may
-        ///     upload the file and refer to the file with "attachment://filename.ext" in the 
-        ///     <see cref="Discord.EmbedBuilder.ImageUrl"/>.
-        /// </remarks>
         /// <returns>
-        ///     A task that represents the asynchrnonous send operation. The task result contains the sent message.
+        ///     A task that represents an asynchronous send operation for delivering the message. The task result
+        ///     contains the sent message.
         /// </returns>
         public static async Task<IUserMessage> SendFileAsync(this IUser user,
             string filePath,
@@ -132,7 +156,7 @@ namespace Discord
         /// <param name="options">The options to be used when sending the request.</param>
         /// <exception cref="ArgumentException"><paramref name="pruneDays" /> is not between 0 to 7.</exception>
         /// <returns>
-        ///     A task that represents the asynchrnous operation for banning a user.
+        ///     A task that represents the asynchronous operation for banning a user.
         /// </returns>
         public static Task BanAsync(this IGuildUser user, int pruneDays = 0, string reason = null, RequestOptions options = null)
             => user.Guild.AddBanAsync(user, pruneDays, reason, options);