From baa8beb3824ed59fb50d269b9e13721fa9f5a04e Mon Sep 17 00:00:00 2001 From: Still Hsu <341464@gmail.com> Date: Sat, 5 May 2018 13:49:42 +0800 Subject: [PATCH] Add XML Docs --- .../Entities/Channels/IMessageChannel.cs | 4 +- src/Discord.Net.Core/Entities/Emotes/Emote.cs | 4 +- src/Discord.Net.Core/Entities/IMentionable.cs | 2 +- src/Discord.Net.Core/Entities/Users/IUser.cs | 11 ++++ .../Extensions/UserExtensions.cs | 60 ++++++++++++++++--- 5 files changed, 69 insertions(+), 12 deletions(-) diff --git a/src/Discord.Net.Core/Entities/Channels/IMessageChannel.cs b/src/Discord.Net.Core/Entities/Channels/IMessageChannel.cs index 9837a3048..51a16c74a 100644 --- a/src/Discord.Net.Core/Entities/Channels/IMessageChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IMessageChannel.cs @@ -20,7 +20,7 @@ namespace Discord Task SendMessageAsync(string text, bool isTTS = false, Embed embed = null, RequestOptions options = null); #if FILESYSTEM /// - /// Sends a file to this message channel, with an optional caption. + /// Sends a file to this message channel with an optional caption. /// /// The file path of the file. /// The message to be sent. @@ -35,7 +35,7 @@ namespace Discord Task SendFileAsync(string filePath, string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null); #endif /// - /// Sends a file to this message channel, with an optional caption. + /// Sends a file to this message channel with an optional caption. /// /// The of the file to be sent. /// The name of the attachment. diff --git a/src/Discord.Net.Core/Entities/Emotes/Emote.cs b/src/Discord.Net.Core/Entities/Emotes/Emote.cs index 32d49fede..68156016b 100644 --- a/src/Discord.Net.Core/Entities/Emotes/Emote.cs +++ b/src/Discord.Net.Core/Entities/Emotes/Emote.cs @@ -59,7 +59,7 @@ namespace Discord } /// Parses an from its raw format. - /// The raw encoding of an emote; for example, <:dab:277855270321782784>. + /// The raw encoding of an emote; for example, <:dab:277855270321782784>. /// An emote. /// Invalid emote format. public static Emote Parse(string text) @@ -70,7 +70,7 @@ namespace Discord } /// Tries to parse an from its raw format. - /// The raw encoding of an emote; for example, <:dab:277855270321782784>. + /// The raw encoding of an emote; for example, <:dab:277855270321782784>. /// An emote. public static bool TryParse(string text, out Emote result) { diff --git a/src/Discord.Net.Core/Entities/IMentionable.cs b/src/Discord.Net.Core/Entities/IMentionable.cs index 225806723..cf4a8662b 100644 --- a/src/Discord.Net.Core/Entities/IMentionable.cs +++ b/src/Discord.Net.Core/Entities/IMentionable.cs @@ -9,7 +9,7 @@ namespace Discord /// Returns a special string used to mention this object. /// /// - /// A string that is recognized by Discord as a mention (e.g. <@168693960628371456>). + /// A string that is recognized by Discord as a mention (e.g. <@168693960628371456>). /// string Mention { get; } } diff --git a/src/Discord.Net.Core/Entities/Users/IUser.cs b/src/Discord.Net.Core/Entities/Users/IUser.cs index f651a23f3..929824ced 100644 --- a/src/Discord.Net.Core/Entities/Users/IUser.cs +++ b/src/Discord.Net.Core/Entities/Users/IUser.cs @@ -14,6 +14,13 @@ namespace Discord /// /// Gets the URL to this user's avatar. /// + /// The format to return. + /// + /// The size of the image to return in. Image size can be any power of two between 16 and 2048. + /// + /// + /// User's avatar URL. + /// string GetAvatarUrl(ImageFormat format = ImageFormat.Auto, ushort size = 128); /// /// Gets the URL to this user's default avatar. @@ -43,6 +50,10 @@ namespace Discord /// /// Returns a direct message channel to this user, or create one if it does not already exist. /// + /// The options to be used when sending the request. + /// + /// An awaitable Task containing the DM channel. + /// Task GetOrCreateDMChannelAsync(RequestOptions options = null); } } diff --git a/src/Discord.Net.Core/Extensions/UserExtensions.cs b/src/Discord.Net.Core/Extensions/UserExtensions.cs index ad00296f7..41e84c3cb 100644 --- a/src/Discord.Net.Core/Extensions/UserExtensions.cs +++ b/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 /// An extension class for various Discord user objects. public static class UserExtensions { - /// Sends a message to the user via DM. + /// + /// Sends a message via DM. + /// + /// The message to be sent. + /// Whether the message should be read aloud by Discord or not. + /// The to be sent. + /// The options to be used when sending the request. + /// + /// An awaitable Task containing the message sent to the channel. + /// public static async Task SendMessageAsync(this IUser user, string text, bool isTTS = false, @@ -16,7 +26,23 @@ namespace Discord return await (await user.GetOrCreateDMChannelAsync().ConfigureAwait(false)).SendMessageAsync(text, isTTS, embed, options).ConfigureAwait(false); } - /// Sends a file to the user via DM. + /// + /// Sends a file to this message channel with an optional caption. + /// + /// The of the file to be sent. + /// The name of the attachment. + /// The message to be sent. + /// Whether the message should be read aloud by Discord or not. + /// The to be sent. + /// The options to be used when sending the request. + /// + /// If you wish to upload an image and have it embedded in a embed, you may + /// upload the file and refer to the file with "attachment://filename.ext" in the + /// . + /// + /// + /// An awaitable Task containing the message sent to the channel. + /// public static async Task SendFileAsync(this IUser user, Stream stream, string filename, @@ -30,7 +56,22 @@ namespace Discord } #if FILESYSTEM - /// Sends a file to the user via DM. + /// + /// Sends a file via DM with an optional caption. + /// + /// The file path of the file. + /// The message to be sent. + /// Whether the message should be read aloud by Discord or not. + /// The to be sent. + /// The options to be used when sending the request. + /// + /// If you wish to upload an image and have it embedded in a embed, you may + /// upload the file and refer to the file with "attachment://filename.ext" in the + /// . + /// + /// + /// An awaitable Task containing the message sent to the channel. + /// public static async Task SendFileAsync(this IUser user, string filePath, string text = null, @@ -41,10 +82,15 @@ namespace Discord return await (await user.GetOrCreateDMChannelAsync().ConfigureAwait(false)).SendFileAsync(filePath, text, isTTS, embed, options).ConfigureAwait(false); } #endif - /// Bans the provided user from the guild and optionally prunes their recent messages. - /// The user to ban. - /// The number of days to remove messages from this user for - must be between [0, 7] - /// The reason of the ban to be written in the audit log. + /// + /// Bans the provided user from the guild and optionally prunes their recent messages. + /// + /// The user to ban. + /// + /// The number of days to remove messages from this user for - must be between [0, 7] + /// + /// The reason of the ban to be written in the audit log. + /// is not between 0 to 7. public static Task BanAsync(this IGuildUser user, int pruneDays = 0, string reason = null, RequestOptions options = null) => user.Guild.AddBanAsync(user, pruneDays, reason, options); }