From 26c81fb4df44b3a0346336c1a14fb42f76e5b0b4 Mon Sep 17 00:00:00 2001 From: Hsu Still <341464@gmail.com> Date: Tue, 17 Apr 2018 09:51:19 +0800 Subject: [PATCH] Add XML docs --- src/Discord.Net.Core/CDN.cs | 40 ++++- src/Discord.Net.Core/DiscordConfig.cs | 59 +++++-- src/Discord.Net.Core/Entities/Emotes/Emoji.cs | 5 + .../Entities/Guilds/IGuild.cs | 7 +- .../Entities/Guilds/IUserGuild.cs | 18 +- src/Discord.Net.Core/Entities/Image.cs | 5 +- .../Entities/Invites/IInvite.cs | 3 + .../Entities/Messages/Embed.cs | 9 + .../Entities/Messages/EmbedAuthor.cs | 26 ++- .../Entities/Messages/EmbedBuilder.cs | 165 +++++++++++++----- .../Entities/Messages/EmbedField.cs | 19 +- src/Discord.Net.Core/Entities/Roles/Color.cs | 29 ++- .../Entities/Roles/ReorderRoleProperties.cs | 5 + src/Discord.Net.Core/Logging/LogMessage.cs | 32 +++- src/Discord.Net.Core/RequestOptions.cs | 24 ++- src/Discord.Net.Core/Utils/Comparers.cs | 18 ++ src/Discord.Net.Core/Utils/Optional.cs | 2 +- .../Entities/Guilds/RestUserGuild.cs | 4 +- 18 files changed, 371 insertions(+), 99 deletions(-) diff --git a/src/Discord.Net.Core/CDN.cs b/src/Discord.Net.Core/CDN.cs index 44bd516b0..44e1779f3 100644 --- a/src/Discord.Net.Core/CDN.cs +++ b/src/Discord.Net.Core/CDN.cs @@ -2,13 +2,19 @@ using System; namespace Discord { - /// A class containing the strings related to various Content Delivery Networks (CDNs). + /// + /// A class containing the strings related to various Content Delivery Networks (CDNs). + /// public static class CDN { - /// Returns the Discord developer application icon. + /// + /// 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 . + /// + /// Returns the user avatar URL based on the and . + /// public static string GetUserAvatarUrl(ulong userId, string avatarId, ushort size, ImageFormat format) { if (avatarId == null) @@ -16,31 +22,47 @@ namespace Discord string extension = FormatToExtension(format, avatarId); return $"{DiscordConfig.CDNUrl}avatars/{userId}/{avatarId}.{extension}?size={size}"; } - /// Returns the default user avatar URL. + /// + /// Returns the default user avatar URL. + /// + /// The discriminator value of a user. public static string GetDefaultUserAvatarUrl(ushort discriminator) { return $"{DiscordConfig.CDNUrl}embed/avatars/{discriminator % 5}.png"; } + /// + /// Returns the icon URL associated with the given guild 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. + /// + /// Returns the guild splash URL associated with the given guild and splash 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. + /// + /// Returns the channel icon URL associated with the given 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. + /// + /// 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 . + /// + /// 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. + /// + /// 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 fce32da1b..b3cdddfa5 100644 --- a/src/Discord.Net.Core/DiscordConfig.cs +++ b/src/Discord.Net.Core/DiscordConfig.cs @@ -2,43 +2,74 @@ using System.Reflection; namespace Discord { + /// + /// Defines various behaviors of Discord.Net. + /// public class DiscordConfig { - /// Returns the gateway version Discord.Net uses. + /// + /// Returns the gateway version Discord.Net uses. + /// public const int APIVersion = 6; - /// Returns the Discord.Net version, including the build number. + /// + /// Gets the Discord.Net version, 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. + /// + /// Gets 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. + /// + /// Returns the base Discord API URL. + /// public static readonly string APIUrl = $"https://discordapp.com/api/v{APIVersion}/"; - /// Returns the base Discord CDN URL. + /// + /// Returns the base Discord CDN URL. + /// public const string CDNUrl = "https://cdn.discordapp.com/"; - /// Returns the base Discord invite URL. + /// + /// Returns the base Discord invite URL. + /// public const string InviteUrl = "https://discord.gg/"; - /// Returns the default timeout for requests. + /// + /// Returns the default timeout for requests. + /// public const int DefaultRequestTimeout = 15000; - /// Returns the max length for a Discord message. + /// + /// Returns the max length for a Discord message. + /// public const int MaxMessageSize = 2000; - /// Returns the max messages allowed to be in a request. + /// + /// 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. + /// + /// 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. + /// + /// 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. + /// + /// Gets or sets how a request should act in the case of an error, by default. + /// public RetryMode DefaultRetryMode { get; set; } = RetryMode.AlwaysRetry; - /// Gets or sets the minimum log level severity that will be sent to the Log event. + /// + /// Gets or sets the minimum log level severity that will be sent to the Log event. + /// public LogSeverity LogLevel { get; set; } = LogSeverity.Info; - /// Gets or sets whether the initial log entry should be printed. + /// + /// Gets or sets whether the initial log entry should be printed. + /// internal bool DisplayInitialLog { get; set; } = true; } } diff --git a/src/Discord.Net.Core/Entities/Emotes/Emoji.cs b/src/Discord.Net.Core/Entities/Emotes/Emoji.cs index a68702dbd..da3c512c5 100644 --- a/src/Discord.Net.Core/Entities/Emotes/Emoji.cs +++ b/src/Discord.Net.Core/Entities/Emotes/Emoji.cs @@ -25,6 +25,10 @@ namespace Discord Name = unicode; } + /// + /// Determines whether the specified emoji is equal to the current emoji. + /// + /// The object to compare with the current object. public override bool Equals(object other) { if (other == null) return false; @@ -36,6 +40,7 @@ namespace Discord return string.Equals(Name, otherEmoji.Name); } + /// public override int GetHashCode() => Name.GetHashCode(); } } diff --git a/src/Discord.Net.Core/Entities/Guilds/IGuild.cs b/src/Discord.Net.Core/Entities/Guilds/IGuild.cs index 87104f1c9..56c094621 100644 --- a/src/Discord.Net.Core/Entities/Guilds/IGuild.cs +++ b/src/Discord.Net.Core/Entities/Guilds/IGuild.cs @@ -5,6 +5,9 @@ using System.Threading.Tasks; namespace Discord { + /// + /// Represents a generic guild object. + /// public interface IGuild : IDeletable, ISnowflakeEntity { /// @@ -17,7 +20,7 @@ namespace Discord /// int AFKTimeout { get; } /// - /// Returns if this guild is embeddable (e.g. widget) + /// Returns if this guild is embeddable (e.g. widget). /// bool IsEmbeddable { get; } /// @@ -68,7 +71,7 @@ namespace Discord /// ulong? EmbedChannelId { get; } /// - /// Gets the ID of the channel where randomized welcome messages are sent, or if not. + /// Gets the ID of the channel where randomized welcome messages are sent if set, or if not. /// ulong? SystemChannelId { get; } /// diff --git a/src/Discord.Net.Core/Entities/Guilds/IUserGuild.cs b/src/Discord.Net.Core/Entities/Guilds/IUserGuild.cs index b27db9377..5da2ce5da 100644 --- a/src/Discord.Net.Core/Entities/Guilds/IUserGuild.cs +++ b/src/Discord.Net.Core/Entities/Guilds/IUserGuild.cs @@ -1,14 +1,22 @@ -namespace Discord +namespace Discord { public interface IUserGuild : IDeletable, ISnowflakeEntity { - /// Gets the name of this guild. + /// + /// Gets the name of this guild. + /// string Name { get; } - /// Returns the url to this guild's icon, or null if one is not set. + /// + /// Gets the icon URL associated with this guild, or if one is not set. + /// string IconUrl { get; } - /// Returns true if the current user owns this guild. + /// + /// Returns if the current user owns this guild. + /// bool IsOwner { get; } - /// Returns the current user's permissions for this guild. + /// + /// Returns the current user's permissions for this guild. + /// GuildPermissions Permissions { get; } } } diff --git a/src/Discord.Net.Core/Entities/Image.cs b/src/Discord.Net.Core/Entities/Image.cs index cc126c2b8..4bdd4be66 100644 --- a/src/Discord.Net.Core/Entities/Image.cs +++ b/src/Discord.Net.Core/Entities/Image.cs @@ -1,4 +1,4 @@ -using System.IO; +using System.IO; namespace Discord { /// @@ -6,6 +6,9 @@ namespace Discord /// public struct Image { + /// + /// Gets the stream to be uploaded to Discord. + /// public Stream Stream { get; } /// /// Create the image with a . diff --git a/src/Discord.Net.Core/Entities/Invites/IInvite.cs b/src/Discord.Net.Core/Entities/Invites/IInvite.cs index e8b683292..1be65face 100644 --- a/src/Discord.Net.Core/Entities/Invites/IInvite.cs +++ b/src/Discord.Net.Core/Entities/Invites/IInvite.cs @@ -2,6 +2,9 @@ using System.Threading.Tasks; namespace Discord { + /// + /// Represents a generic invite object. + /// public interface IInvite : IEntity, IDeletable { /// diff --git a/src/Discord.Net.Core/Entities/Messages/Embed.cs b/src/Discord.Net.Core/Entities/Messages/Embed.cs index 6ea7c0bd5..1f2846f2e 100644 --- a/src/Discord.Net.Core/Entities/Messages/Embed.cs +++ b/src/Discord.Net.Core/Entities/Messages/Embed.cs @@ -5,6 +5,9 @@ using System.Linq; namespace Discord { + /// + /// Represents an embed object seen in an . + /// [DebuggerDisplay(@"{DebuggerDisplay,nq}")] public class Embed : IEmbed { @@ -70,8 +73,14 @@ namespace Discord Fields = fields; } + /// + /// Gets the total length of all embed properties. + /// public int Length => Title?.Length + Author?.Name?.Length + Description?.Length + Footer?.Text?.Length + Fields.Sum(f => f.Name.Length + f.Value.ToString().Length) ?? 0; + /// + /// Gets the title of the embed. + /// public override string ToString() => Title; private string DebuggerDisplay => $"{Title} ({Type})"; } diff --git a/src/Discord.Net.Core/Entities/Messages/EmbedAuthor.cs b/src/Discord.Net.Core/Entities/Messages/EmbedAuthor.cs index 9d7cfdf18..e19d7619a 100644 --- a/src/Discord.Net.Core/Entities/Messages/EmbedAuthor.cs +++ b/src/Discord.Net.Core/Entities/Messages/EmbedAuthor.cs @@ -3,17 +3,27 @@ using System.Diagnostics; namespace Discord { - /// An author field for an . + /// + /// Represents a author field of an . + /// [DebuggerDisplay("{DebuggerDisplay,nq}")] public struct EmbedAuthor { - /// Gets the name of the author field. + /// + /// Gets the name of the author field. + /// public string Name { get; internal set; } - /// Gets the URL of the author field. + /// + /// Gets the URL of the author field. + /// public string Url { get; internal set; } - /// Gets the icon URL of the author field. + /// + /// Gets the icon URL of the author field. + /// public string IconUrl { get; internal set; } - /// Gets the proxified icon URL of the author field. + /// + /// Gets the proxified icon URL of the author field. + /// public string ProxyIconUrl { get; internal set; } internal EmbedAuthor(string name, string url, string iconUrl, string proxyIconUrl) @@ -25,6 +35,12 @@ namespace Discord } private string DebuggerDisplay => $"{Name} ({Url})"; + /// + /// Gets the name of the author field. + /// + /// + /// + /// public override string ToString() => Name; } } diff --git a/src/Discord.Net.Core/Entities/Messages/EmbedBuilder.cs b/src/Discord.Net.Core/Entities/Messages/EmbedBuilder.cs index 85765e3b5..fa7d87410 100644 --- a/src/Discord.Net.Core/Entities/Messages/EmbedBuilder.cs +++ b/src/Discord.Net.Core/Entities/Messages/EmbedBuilder.cs @@ -5,7 +5,9 @@ using System.Linq; namespace Discord { - /// A builder for creating an to be sent. + /// + /// Represents a builder class for creating a . + /// public class EmbedBuilder { private string _title; @@ -15,16 +17,24 @@ namespace Discord private EmbedThumbnail? _thumbnail; private List _fields; - /// The maximum number of fields allowed by Discord. + /// + /// Returns the maximum number of fields allowed by Discord. + /// public const int MaxFieldCount = 25; - /// The maximum length of title allowed by Discord. + /// + /// Returns the maximum length of title allowed by Discord. + /// public const int MaxTitleLength = 256; - /// The maximum length of description allowed by Discord. + /// + /// Returns the maximum length of description allowed by Discord. + /// public const int MaxDescriptionLength = 2048; - /// The maximum length of total characters allowed by Discord. + /// + /// Returns the maximum length of total characters allowed by Discord. + /// public const int MaxEmbedLength = 6000; - /// Creates a new . + /// Initializes a new class. public EmbedBuilder() { Fields = new List(); @@ -102,6 +112,9 @@ namespace Discord /// Gets or sets the of an . public EmbedFooterBuilder Footer { get; set; } + /// + /// Gets the total length of all embed properties. + /// public int Length { get @@ -116,69 +129,91 @@ namespace Discord } } + /// + /// Sets the title of an . + /// + /// The title to be set. public EmbedBuilder WithTitle(string title) { Title = title; return this; } - /// Sets the description of an . + /// + /// Sets the description of an . + /// /// The description to be set. public EmbedBuilder WithDescription(string description) { Description = description; return this; } - /// Sets the URL of an . + /// + /// Sets the URL of an . + /// /// The URL to be set. public EmbedBuilder WithUrl(string url) { Url = url; return this; } - /// Sets the thumbnail URL of an . + /// + /// Sets the thumbnail URL of an . + /// /// The thumbnail URL to be set. public EmbedBuilder WithThumbnailUrl(string thumbnailUrl) { ThumbnailUrl = thumbnailUrl; return this; } - /// Sets the image URL of an . - /// The image URL to be set. + /// + /// Sets the image URL of an . + /// + /// The image URL to be set. public EmbedBuilder WithImageUrl(string imageUrl) { ImageUrl = imageUrl; return this; } - /// Sets the timestamp of an to the current time. + /// + /// Sets the timestamp of an to the current time. + /// public EmbedBuilder WithCurrentTimestamp() { Timestamp = DateTimeOffset.UtcNow; return this; } - /// Sets the timestamp of an . - /// The timestamp to be set. + /// + /// Sets the timestamp of an . + /// + /// The timestamp to be set. public EmbedBuilder WithTimestamp(DateTimeOffset dateTimeOffset) { Timestamp = dateTimeOffset; return this; } - /// Sets the sidebar color of an . - /// The color to be set. + /// + /// Sets the sidebar color of an . + /// + /// The color to be set. public EmbedBuilder WithColor(Color color) { Color = color; return this; } - /// Sets the of an . - /// The author builder class containing the author field properties. + /// + /// Sets the of an . + /// + /// The author builder class containing the author field properties. public EmbedBuilder WithAuthor(EmbedAuthorBuilder author) { Author = author; return this; } - /// Sets the author field of an with the provided properties. - /// The delegate containing the author field properties. + /// + /// Sets the author field of an with the provided properties. + /// + /// The containing the author field properties. public EmbedBuilder WithAuthor(Action action) { var author = new EmbedAuthorBuilder(); @@ -186,10 +221,12 @@ namespace Discord Author = author; return this; } - /// Sets the author field of an with the provided name, icon URL, and URL. - /// The title of the author field. - /// The icon URL of the author field. - /// The URL of the author field. + /// + /// Sets the author field of an with the provided name, icon URL, and URL. + /// + /// The title of the author field. + /// The icon URL of the author field. + /// The URL of the author field. public EmbedBuilder WithAuthor(string name, string iconUrl = null, string url = null) { var author = new EmbedAuthorBuilder @@ -201,15 +238,19 @@ namespace Discord Author = author; return this; } - /// Sets the of an . - /// The footer builder class containing the footer field properties. + /// + /// Sets the of an . + /// + /// The footer builder class containing the footer field properties. public EmbedBuilder WithFooter(EmbedFooterBuilder footer) { Footer = footer; return this; } - /// Sets the footer field of an with the provided properties. - /// The delegate containing the footer field properties. + /// + /// Sets the footer field of an with the provided properties. + /// + /// The containing the footer field properties. public EmbedBuilder WithFooter(Action action) { var footer = new EmbedFooterBuilder(); @@ -217,9 +258,11 @@ namespace Discord Footer = footer; return this; } - /// Sets the footer field of an with the provided name, icon URL. - /// The title of the footer field. - /// The icon URL of the footer field. + /// + /// Sets the footer field of an with the provided name, icon URL. + /// + /// The title of the footer field. + /// The icon URL of the footer field. public EmbedBuilder WithFooter(string text, string iconUrl = null) { var footer = new EmbedFooterBuilder @@ -231,10 +274,12 @@ namespace Discord return this; } - /// Adds an field with the provided name and value. - /// The title of the field. - /// The value of the field. - /// Indicates whether the field is in-line or not. + /// + /// Adds an field with the provided name and value. + /// + /// The title of the field. + /// The value of the field. + /// Indicates whether the field is in-line or not. public EmbedBuilder AddField(string name, object value, bool inline = false) { var field = new EmbedFieldBuilder() @@ -244,8 +289,11 @@ namespace Discord AddField(field); return this; } - /// Adds a field with the provided to an . - /// The field builder class containing the field properties. + /// + /// Adds a field with the provided to an + /// . + /// + /// The field builder class containing the field properties. public EmbedBuilder AddField(EmbedFieldBuilder field) { if (Fields.Count >= MaxFieldCount) @@ -256,8 +304,10 @@ namespace Discord Fields.Add(field); return this; } - /// Adds an field with the provided properties. - /// The delegate containing the field properties. + /// + /// Adds an field with the provided properties. + /// + /// The containing the field properties. public EmbedBuilder AddField(Action action) { var field = new EmbedFieldBuilder(); @@ -266,8 +316,12 @@ namespace Discord return this; } - /// Builds the into a Rich Embed format. - /// The built embed object. + /// + /// Builds the into a Rich Embed format. + /// + /// + /// The built embed object. + /// public Embed Build() { if (Length > MaxEmbedLength) @@ -286,9 +340,18 @@ namespace Discord private string _name; private string _value; private EmbedField _field; + /// + /// Gets the maximum field length for name allowed by Discord. + /// public const int MaxFieldNameLength = 256; + /// + /// Gets the maximum field length for value allowed by Discord. + /// public const int MaxFieldValueLength = 1024; + /// + /// Gets or sets the field name. + /// public string Name { get => _name; @@ -300,6 +363,9 @@ namespace Discord } } + /// + /// Gets or sets the field value. + /// public object Value { get => _value; @@ -311,24 +377,41 @@ namespace Discord _value = stringValue; } } + /// + /// Gets or sets whether the field should be in-line with each other. + /// public bool IsInline { get; set; } + /// + /// Sets the field name. + /// + /// The name to set the field name to. public EmbedFieldBuilder WithName(string name) { Name = name; return this; } + /// + /// Sets the field value. + /// + /// The value to set the field value to. public EmbedFieldBuilder WithValue(object value) { Value = value; return this; } + /// + /// Sets whether the field should be in-line with each other. + /// public EmbedFieldBuilder WithIsInline(bool isInline) { IsInline = isInline; return this; } + /// + /// Builds the field builder into a class. + /// public EmbedField Build() => new EmbedField(Name, Value.ToString(), IsInline); } diff --git a/src/Discord.Net.Core/Entities/Messages/EmbedField.cs b/src/Discord.Net.Core/Entities/Messages/EmbedField.cs index 2bc4ae436..40404167d 100644 --- a/src/Discord.Net.Core/Entities/Messages/EmbedField.cs +++ b/src/Discord.Net.Core/Entities/Messages/EmbedField.cs @@ -2,15 +2,23 @@ using System.Diagnostics; namespace Discord { - /// A field for an . + /// + /// Represents a field for an . + /// [DebuggerDisplay("{DebuggerDisplay,nq}")] public struct EmbedField { - /// Gets the name of the field. + /// + /// Gets the name of the field. + /// public string Name { get; internal set; } - /// Gets the value of the field. + /// + /// Gets the value of the field. + /// public string Value { get; internal set; } - /// Gets whether the field is inline inside an or not. + /// + /// Gets whether the field should be in-line with each other. + /// public bool Inline { get; internal set; } internal EmbedField(string name, string value, bool inline) @@ -21,6 +29,9 @@ namespace Discord } private string DebuggerDisplay => $"{Name} ({Value}"; + /// + /// Gets the name of the field. + /// public override string ToString() => Name; } } diff --git a/src/Discord.Net.Core/Entities/Roles/Color.cs b/src/Discord.Net.Core/Entities/Roles/Color.cs index 014949bde..b84bbb313 100644 --- a/src/Discord.Net.Core/Entities/Roles/Color.cs +++ b/src/Discord.Net.Core/Entities/Roles/Color.cs @@ -4,7 +4,7 @@ using System.Diagnostics; namespace Discord { /// - /// A color object that Discord uses. + /// Represents a Discord color. /// [DebuggerDisplay(@"{DebuggerDisplay,nq}")] public struct Color @@ -62,10 +62,20 @@ namespace Discord /// Gets the blue component for this color. public byte B => (byte)(RawValue); + /// + /// Initializes a struct with the given raw value. + /// + /// A raw value for the color (e.g. 0x607D8B). public Color(uint rawValue) { RawValue = rawValue; } + /// + /// Initializes a struct with the given RGB bytes. + /// + /// The that represents the red color. + /// The that represents the green color. + /// The that represents the blue color. public Color(byte r, byte g, byte b) { RawValue = @@ -73,6 +83,12 @@ namespace Discord ((uint)g << 8) | (uint)b; } + /// + /// Initializes a struct with the given RGB value. + /// + /// The value that represents the red color. Must be within 0~255. + /// The value that represents the green color. Must be within 0~255. + /// The value that represents the blue color. Must be within 0~255. public Color(int r, int g, int b) { if (r < 0 || r > 255) @@ -86,6 +102,12 @@ namespace Discord ((uint)g << 8) | (uint)b; } + /// + /// Initializes a struct with the given RGB float value. + /// + /// The value that represents the red color. Must be within 0~1. + /// The value that represents the green color. Must be within 0~1. + /// The value that represents the blue color. Must be within 0~1. public Color(float r, float g, float b) { if (r < 0.0f || r > 1.0f) @@ -99,7 +121,10 @@ namespace Discord ((uint)(g * 255.0f) << 8) | (uint)(b * 255.0f); } - + + /// + /// Gets the hexadecimal representation of the color (e.g. #000ccc). + /// public override string ToString() => $"#{Convert.ToString(RawValue, 16)}"; private string DebuggerDisplay => diff --git a/src/Discord.Net.Core/Entities/Roles/ReorderRoleProperties.cs b/src/Discord.Net.Core/Entities/Roles/ReorderRoleProperties.cs index 5359d8e9e..fcfa08da5 100644 --- a/src/Discord.Net.Core/Entities/Roles/ReorderRoleProperties.cs +++ b/src/Discord.Net.Core/Entities/Roles/ReorderRoleProperties.cs @@ -14,6 +14,11 @@ namespace Discord /// public int Position { get; } + /// + /// Initializes a with the given role ID and position. + /// + /// The ID of the role to be edited. + /// The new zero-based position of the role. public ReorderRoleProperties(ulong id, int pos) { Id = id; diff --git a/src/Discord.Net.Core/Logging/LogMessage.cs b/src/Discord.Net.Core/Logging/LogMessage.cs index 7c382f95f..7d6f8c13c 100644 --- a/src/Discord.Net.Core/Logging/LogMessage.cs +++ b/src/Discord.Net.Core/Logging/LogMessage.cs @@ -3,18 +3,36 @@ using System.Text; namespace Discord { - /// The message object for logging purposes. + /// + /// Represents a message used for logging purposes. + /// public struct LogMessage { - /// The severity of the log message. + /// + /// Gets the severity of the log message. + /// public LogSeverity Severity { get; } - /// The source of the log message. + /// + /// Gets the source of the log message. + /// public string Source { get; } - /// The message of the log message. + /// + /// Gets the message of the log message. + /// public string Message { get; } - /// The exception of the log message. + /// + /// Gets the exception of the log message. + /// public Exception Exception { get; } + /// + /// Initializes a new with the severity, source, + /// of the event, and optionally, an exception. + /// + /// The severity of the event. + /// The source of the event. + /// The message of the event. + /// The exception of the event. public LogMessage(LogSeverity severity, string source, string message, Exception exception = null) { Severity = severity; @@ -22,8 +40,8 @@ namespace Discord Message = message; Exception = exception; } - - public override string ToString() => ToString(null); + + public override string ToString() => ToString(); public string ToString(StringBuilder builder = null, bool fullException = true, bool prependTimestamp = true, DateTimeKind timestampKind = DateTimeKind.Local, int? padSource = 11) { string sourceName = Source; diff --git a/src/Discord.Net.Core/RequestOptions.cs b/src/Discord.Net.Core/RequestOptions.cs index 5f3a8814b..e276a7391 100644 --- a/src/Discord.Net.Core/RequestOptions.cs +++ b/src/Discord.Net.Core/RequestOptions.cs @@ -1,21 +1,29 @@ -using System.Threading; +using System.Threading; namespace Discord { public class RequestOptions { + /// + /// Creates a new class with its default settings. + /// public static RequestOptions Default => new RequestOptions(); - /// - /// The max time, in milliseconds, to wait for this request to complete. If null, a request will not time out. - /// If a rate limit has been triggered for this request's bucket and will not be unpaused in time, this request will fail immediately. + /// + /// Gets or set the max time, in milliseconds, to wait for this request to complete. If + /// , a request will not time out. If a rate limit has been triggered for this + /// request's bucket and will not be unpaused in time, this request will fail immediately. /// public int? Timeout { get; set; } public CancellationToken CancelToken { get; set; } = CancellationToken.None; + /// + /// Gets or sets the retry behavior when the request fails. + /// public RetryMode? RetryMode { get; set; } public bool HeaderOnly { get; internal set; } /// - /// The reason for this action in the guild's audit log + /// Gets or sets the reason for this action in the guild's audit log. Note that this property may not apply + /// to every action. /// public string AuditLogReason { get; set; } @@ -31,11 +39,15 @@ namespace Discord return options.Clone(); } + /// + /// Initializes a new class with the default request timeout set in + /// . + /// public RequestOptions() { Timeout = DiscordConfig.DefaultRequestTimeout; } - + public RequestOptions Clone() => MemberwiseClone() as RequestOptions; } } diff --git a/src/Discord.Net.Core/Utils/Comparers.cs b/src/Discord.Net.Core/Utils/Comparers.cs index d7641e897..d7092d9cc 100644 --- a/src/Discord.Net.Core/Utils/Comparers.cs +++ b/src/Discord.Net.Core/Utils/Comparers.cs @@ -3,13 +3,31 @@ using System.Collections.Generic; namespace Discord { + /// + /// Represents a collection of for various Discord objects. + /// public static class DiscordComparers { // TODO: simplify with '??=' slated for C# 8.0 + /// + /// Gets an to be used to compare users. + /// public static IEqualityComparer UserComparer => _userComparer ?? (_userComparer = new EntityEqualityComparer()); + /// + /// Gets an to be used to compare guilds. + /// public static IEqualityComparer GuildComparer => _guildComparer ?? (_guildComparer = new EntityEqualityComparer()); + /// + /// Gets an to be used to compare channels. + /// public static IEqualityComparer ChannelComparer => _channelComparer ?? (_channelComparer = new EntityEqualityComparer()); + /// + /// Gets an to be used to compare roles. + /// public static IEqualityComparer RoleComparer => _roleComparer ?? (_roleComparer = new EntityEqualityComparer()); + /// + /// Gets an to be used to compare messages. + /// public static IEqualityComparer MessageComparer => _messageComparer ?? (_messageComparer = new EntityEqualityComparer()); private static IEqualityComparer _userComparer; diff --git a/src/Discord.Net.Core/Utils/Optional.cs b/src/Discord.Net.Core/Utils/Optional.cs index eb3cbdca2..9284645f5 100644 --- a/src/Discord.Net.Core/Utils/Optional.cs +++ b/src/Discord.Net.Core/Utils/Optional.cs @@ -1,4 +1,4 @@ -using System; +using System; using System.Diagnostics; namespace Discord diff --git a/src/Discord.Net.Rest/Entities/Guilds/RestUserGuild.cs b/src/Discord.Net.Rest/Entities/Guilds/RestUserGuild.cs index 6bc9cea7a..de5a5f7d9 100644 --- a/src/Discord.Net.Rest/Entities/Guilds/RestUserGuild.cs +++ b/src/Discord.Net.Rest/Entities/Guilds/RestUserGuild.cs @@ -1,4 +1,4 @@ -using System; +using System; using System.Diagnostics; using System.Threading.Tasks; using Model = Discord.API.UserGuild; @@ -6,7 +6,7 @@ using Model = Discord.API.UserGuild; namespace Discord.Rest { [DebuggerDisplay(@"{DebuggerDisplay,nq}")] - public class RestUserGuild : RestEntity, ISnowflakeEntity, IUserGuild + public class RestUserGuild : RestEntity, IUserGuild { private string _iconId;