Add XML Docs

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

@@ -20,7 +20,7 @@ public interface IMessageChannel : IChannel
         Task<IUserMessage> SendMessageAsync(string text, bool isTTS = false, Embed embed = null, RequestOptions options = null);
 #if FILESYSTEM
         /// <summary>
-        ///     Sends a file to this message channel, with an optional caption.
+        ///     Sends a file to this message channel with an optional caption.
         /// </summary>
         /// <param name="filePath">The file path of the file.</param>
         /// <param name="text">The message to be sent.</param>
@@ -35,7 +35,7 @@ public interface IMessageChannel : IChannel
         Task<IUserMessage> SendFileAsync(string filePath, string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null);
 #endif
         /// <summary>
-        ///     Sends a file to this message channel, with an optional caption.
+        ///     Sends a file to this message channel with an optional caption.
         /// </summary>
         /// <param name="stream">The <see cref="Stream"/> of the file to be sent.</param>
         /// <param name="filename">The name of the attachment.</param>

src/Discord.Net.Core/Entities/Emotes/Emote.cs

@@ -59,7 +59,7 @@ public override int GetHashCode()
         }
 
         /// <summary> Parses an <see cref="Emote"/> from its raw format. </summary>
-        /// <param name="text">The raw encoding of an emote; for example, &lt;:dab:277855270321782784&gt;.</param>
+        /// <param name="text">The raw encoding of an emote; for example, <:dab:277855270321782784&gt;.</param>
         /// <returns>An emote.</returns>
         /// <exception cref="ArgumentException">Invalid emote format.</exception>
         public static Emote Parse(string text)
@@ -70,7 +70,7 @@ public static Emote Parse(string text)
         }
 
         /// <summary> Tries to parse an <see cref="Emote"/> from its raw format. </summary>
-        /// <param name="text">The raw encoding of an emote; for example, &lt;:dab:277855270321782784&gt;.</param>
+        /// <param name="text">The raw encoding of an emote; for example, <:dab:277855270321782784&gt;.</param>
         /// <param name="result">An emote.</param>
         public static bool TryParse(string text, out Emote result)
         {

src/Discord.Net.Core/Entities/IMentionable.cs

@@ -9,7 +9,7 @@ public interface IMentionable
         ///     Returns a special string used to mention this object.
         /// </summary>
         /// <returns>
-        ///     A string that is recognized by Discord as a mention (e.g. &lt;@168693960628371456&gt;).
+        ///     A string that is recognized by Discord as a mention (e.g. <@168693960628371456&gt;).
         /// </returns>
         string Mention { get; }
     }

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

@@ -14,6 +14,13 @@ public interface IUser : ISnowflakeEntity, IMentionable, IPresence
         /// <summary>
         ///     Gets the URL to this user's avatar.
         /// </summary>
+        /// <param name="format">The format to return.</param>
+        /// <param name="size">
+        /// The size of the image to return in. Image size can be any power of two between 16 and 2048.
+        /// </param>
+        /// <returns>
+        ///     User's avatar URL.
+        /// </returns>
         string GetAvatarUrl(ImageFormat format = ImageFormat.Auto, ushort size = 128);
         /// <summary>
         ///     Gets the URL to this user's default avatar.
@@ -43,6 +50,10 @@ public interface IUser : ISnowflakeEntity, IMentionable, IPresence
         /// <summary>
         ///     Returns a direct message channel to this user, or create one if it does not already exist.
         /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable Task containing the DM channel.
+        /// </returns>
         Task<IDMChannel> GetOrCreateDMChannelAsync(RequestOptions options = null);
     }
 }

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

@@ -1,3 +1,4 @@
+using System;
 using System.Threading.Tasks;
 using System.IO;
 
@@ -6,7 +7,16 @@ namespace Discord
     /// <summary> An extension class for various Discord user objects. </summary>
     public static class UserExtensions
     {
-        /// <summary> Sends a message to the user via DM. </summary>
+        /// <summary>
+        ///     Sends a message via DM.
+        /// </summary>
+        /// <param name="text">The message to be sent.</param>
+        /// <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>
+        /// <returns>
+        ///     An awaitable Task containing the message sent to the channel.
+        /// </returns>
         public static async Task<IUserMessage> SendMessageAsync(this IUser user,
             string text,
             bool isTTS = false,
@@ -16,7 +26,23 @@ public static async Task<IUserMessage> SendMessageAsync(this IUser user,
             return await (await user.GetOrCreateDMChannelAsync().ConfigureAwait(false)).SendMessageAsync(text, isTTS, embed, options).ConfigureAwait(false);
         }
 
-        /// <summary> Sends a file to the user via DM. </summary>
+        /// <summary>
+        ///     Sends a file to this message channel with an optional caption.
+        /// </summary>
+        /// <param name="stream">The <see cref="Stream"/> of the file to be sent.</param>
+        /// <param name="filename">The name of the attachment.</param>
+        /// <param name="text">The message to be sent.</param>
+        /// <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>
+        ///     An awaitable Task containing the message sent to the channel.
+        /// </returns>
         public static async Task<IUserMessage> SendFileAsync(this IUser user,
             Stream stream,
             string filename,
@@ -30,7 +56,22 @@ public static async Task<IUserMessage> SendFileAsync(this IUser user,
         }
 
 #if FILESYSTEM
-        /// <summary> Sends a file to the user via DM. </summary>
+        /// <summary>
+        ///     Sends a file via DM with an optional caption.
+        /// </summary>
+        /// <param name="filePath">The file path of the file.</param>
+        /// <param name="text">The message to be sent.</param>
+        /// <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>
+        ///     An awaitable Task containing the message sent to the channel.
+        /// </returns>
         public static async Task<IUserMessage> SendFileAsync(this IUser user,
             string filePath,
             string text = null,
@@ -41,10 +82,15 @@ public static async Task<IUserMessage> SendFileAsync(this IUser user,
             return await (await user.GetOrCreateDMChannelAsync().ConfigureAwait(false)).SendFileAsync(filePath, text, isTTS, embed, options).ConfigureAwait(false);
         }
 #endif
-        /// <summary> Bans the provided user from the guild and optionally prunes their recent messages. </summary>
-        /// <param name="user"> The user to ban. </param>
-        /// <param name="pruneDays"> The number of days to remove messages from this user for - must be between [0, 7]</param>
-        /// <param name="reason"> The reason of the ban to be written in the audit log. </param>
+        /// <summary>
+        ///     Bans the provided user from the guild and optionally prunes their recent messages.
+        /// </summary>
+        /// <param name="user">The user to ban.</param>
+        /// <param name="pruneDays">
+        /// The number of days to remove messages from this user for - must be between [0, 7]
+        /// </param>
+        /// <param name="reason">The reason of the ban to be written in the audit log.</param>
+        /// <exception cref="ArgumentException"><paramref name="pruneDays" /> is not between 0 to 7.</exception>
         public static Task BanAsync(this IGuildUser user, int pruneDays = 0, string reason = null, RequestOptions options = null)
             => user.Guild.AddBanAsync(user, pruneDays, reason, options);
     }