From 0979a7cac4f7b432adb56a0b8763f6ad8603dee1 Mon Sep 17 00:00:00 2001 From: Hsu Still <341464@gmail.com> Date: Wed, 21 Mar 2018 00:24:04 +0800 Subject: [PATCH] Add XMLDocs for common entities + DiscordConfig + CDN + MentionUtils + LogMessage + LogSeverity --- src/Discord.Net.Core/CDN.cs | 8 ++++++++ src/Discord.Net.Core/DiscordConfig.cs | 17 ++++++++++++++--- src/Discord.Net.Core/Logging/LogMessage.cs | 7 ++++++- src/Discord.Net.Core/Logging/LogSeverity.cs | 21 ++++++++++++++++++++- src/Discord.Net.Core/Utils/MentionUtils.cs | 7 +++++-- 5 files changed, 53 insertions(+), 7 deletions(-) diff --git a/src/Discord.Net.Core/CDN.cs b/src/Discord.Net.Core/CDN.cs index f23f55238..f18adbd7c 100644 --- a/src/Discord.Net.Core/CDN.cs +++ b/src/Discord.Net.Core/CDN.cs @@ -4,8 +4,10 @@ namespace Discord { public static class CDN { + /// Returns the Discord developer application icon. public static string GetApplicationIconUrl(ulong appId, string iconId) => iconId != null ? $"{DiscordConfig.CDNUrl}app-icons/{appId}/{iconId}.jpg" : null; + /// Returns the user avatar URL based on the size and . public static string GetUserAvatarUrl(ulong userId, string avatarId, ushort size, ImageFormat format) { if (avatarId == null) @@ -13,21 +15,27 @@ namespace Discord string extension = FormatToExtension(format, avatarId); return $"{DiscordConfig.CDNUrl}avatars/{userId}/{avatarId}.{extension}?size={size}"; } + /// Returns the guild icon URL based on the guild and icon ID. public static string GetGuildIconUrl(ulong guildId, string iconId) => iconId != null ? $"{DiscordConfig.CDNUrl}icons/{guildId}/{iconId}.jpg" : null; + /// Returns the guild splash URL based on the guild and icon ID. public static string GetGuildSplashUrl(ulong guildId, string splashId) => splashId != null ? $"{DiscordConfig.CDNUrl}splashes/{guildId}/{splashId}.jpg" : null; + /// Returns the channel icon URL based on the guild and icon ID. public static string GetChannelIconUrl(ulong channelId, string iconId) => iconId != null ? $"{DiscordConfig.CDNUrl}channel-icons/{channelId}/{iconId}.jpg" : null; + /// Returns the emoji URL based on the emoji ID. public static string GetEmojiUrl(ulong emojiId, bool animated) => $"{DiscordConfig.CDNUrl}emojis/{emojiId}.{(animated ? "gif" : "png")}"; + /// Returns the rich presence asset URL based on the asset ID and . public static string GetRichAssetUrl(ulong appId, string assetId, ushort size, ImageFormat format) { string extension = FormatToExtension(format, ""); return $"{DiscordConfig.CDNUrl}app-assets/{appId}/{assetId}.{extension}?size={size}"; } + /// Returns the Spotify album URL based on the album art ID. public static string GetSpotifyAlbumArtUrl(string albumArtId) => $"https://i.scdn.co/image/{albumArtId}"; diff --git a/src/Discord.Net.Core/DiscordConfig.cs b/src/Discord.Net.Core/DiscordConfig.cs index fd2fe92e8..6b50adc5c 100644 --- a/src/Discord.Net.Core/DiscordConfig.cs +++ b/src/Discord.Net.Core/DiscordConfig.cs @@ -1,24 +1,35 @@ -using System.Reflection; +using System.Reflection; namespace Discord { public class DiscordConfig { - public const int APIVersion = 6; + /// Returns the gateway version Discord.NET uses. + public const int APIVersion = 6; + /// Returns the Discord.NET verion, including the build number. public static string Version { get; } = typeof(DiscordConfig).GetTypeInfo().Assembly.GetCustomAttribute()?.InformationalVersion ?? typeof(DiscordConfig).GetTypeInfo().Assembly.GetName().Version.ToString(3) ?? "Unknown"; - + + /// Returns the user agent that Discord.NET uses in its clients. public static string UserAgent { get; } = $"DiscordBot (https://github.com/RogueException/Discord.Net, v{Version})"; + /// Returns the base Discord API URL. public static readonly string APIUrl = $"https://discordapp.com/api/v{APIVersion}/"; + /// Returns the base Discord CDN URL. public const string CDNUrl = "https://cdn.discordapp.com/"; + /// Returns the base Discord invite URL. public const string InviteUrl = "https://discord.gg/"; + /// Returns the default timeout for requests. public const int DefaultRequestTimeout = 15000; + /// Returns the max length for a Discord message. public const int MaxMessageSize = 2000; + /// Returns the max messages allowed to be in a request. public const int MaxMessagesPerBatch = 100; + /// Returns the max users allowed to be in a request. public const int MaxUsersPerBatch = 1000; + /// Returns the max guilds allowed to be in a request. public const int MaxGuildsPerBatch = 100; /// Gets or sets how a request should act in the case of an error, by default. diff --git a/src/Discord.Net.Core/Logging/LogMessage.cs b/src/Discord.Net.Core/Logging/LogMessage.cs index d1b3782be..7c382f95f 100644 --- a/src/Discord.Net.Core/Logging/LogMessage.cs +++ b/src/Discord.Net.Core/Logging/LogMessage.cs @@ -1,13 +1,18 @@ -using System; +using System; using System.Text; namespace Discord { + /// The message object for logging purposes. public struct LogMessage { + /// The severity of the log message. public LogSeverity Severity { get; } + /// The source of the log message. public string Source { get; } + /// The message of the log message. public string Message { get; } + /// The exception of the log message. public Exception Exception { get; } public LogMessage(LogSeverity severity, string source, string message, Exception exception = null) diff --git a/src/Discord.Net.Core/Logging/LogSeverity.cs b/src/Discord.Net.Core/Logging/LogSeverity.cs index 785b0ef46..98a822425 100644 --- a/src/Discord.Net.Core/Logging/LogSeverity.cs +++ b/src/Discord.Net.Core/Logging/LogSeverity.cs @@ -1,12 +1,31 @@ -namespace Discord +namespace Discord { public enum LogSeverity { + /// + /// Logs that contain the most severe level of error. + /// This type of error indicate that immediate attention may be required. + /// Critical = 0, + /// + /// Logs that highlight when the flow of execution is stopped due to a failure. + /// Error = 1, + /// + /// Logs that highlight an abnormal activity in the flow of execution. + /// Warning = 2, + /// + /// Logs that track the general flow of the application. + /// Info = 3, + /// + /// Logs that are used for interactive investigation during development. + /// Verbose = 4, + /// + /// Logs that contain the most detailed messages. + /// Debug = 5 } } diff --git a/src/Discord.Net.Core/Utils/MentionUtils.cs b/src/Discord.Net.Core/Utils/MentionUtils.cs index 6c69827b4..bdc4a80ae 100644 --- a/src/Discord.Net.Core/Utils/MentionUtils.cs +++ b/src/Discord.Net.Core/Utils/MentionUtils.cs @@ -1,4 +1,4 @@ -using System; +using System; using System.Globalization; using System.Text; @@ -10,10 +10,13 @@ namespace Discord //If the system can't be positive a user doesn't have a nickname, assume useNickname = true (source: Jake) internal static string MentionUser(string id, bool useNickname = true) => useNickname ? $"<@!{id}>" : $"<@{id}>"; + /// Returns a mention string based on the user ID. public static string MentionUser(ulong id) => MentionUser(id.ToString(), true); internal static string MentionChannel(string id) => $"<#{id}>"; + /// Returns a mention string based on the channel ID. public static string MentionChannel(ulong id) => MentionChannel(id.ToString()); - internal static string MentionRole(string id) => $"<@&{id}>"; + internal static string MentionRole(string id) => $"<@&{id}>"; + /// Returns a mention string based on the role ID. public static string MentionRole(ulong id) => MentionRole(id.ToString()); /// Parses a provided user mention string.