diff --git a/src/Discord.Net.Core/Entities/Channels/IMessageChannel.cs b/src/Discord.Net.Core/Entities/Channels/IMessageChannel.cs index 803e07ff6..0bb6f7818 100644 --- a/src/Discord.Net.Core/Entities/Channels/IMessageChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IMessageChannel.cs @@ -53,18 +53,20 @@ namespace Discord /// . /// /// - /// An awaitable Task containing the message sent to the channel. + /// An awaitable containing the message sent to the channel. /// Task SendFileAsync(Stream stream, string filename, string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null); /// - /// Gets a message from this message channel with the given id, or null if not found. + /// Gets a message from this message channel. /// /// The ID of the message. - /// The that determines whether the object should be fetched from cache. + /// The that determines whether the object should be fetched from + /// cache. /// The options to be used when sending the request. /// - /// The message gotten from either the cache or the download, or null if none is found. + /// An awaitable containing the message gotten from either the cache or the download; + /// null if none is found or if the message fails to be retrieved. /// Task GetMessageAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); @@ -94,7 +96,6 @@ namespace Discord /// IAsyncEnumerable> GetMessagesAsync(ulong fromMessageId, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); - /// /// Gets a collection of messages in this channel. /// diff --git a/src/Discord.Net.Core/Entities/Channels/ITextChannel.cs b/src/Discord.Net.Core/Entities/Channels/ITextChannel.cs index a2dce09ec..d043297b2 100644 --- a/src/Discord.Net.Core/Entities/Channels/ITextChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/ITextChannel.cs @@ -55,7 +55,7 @@ namespace Discord /// The properties to modify the channel with. /// The options to be used when sending the request. Task ModifyAsync(Action func, RequestOptions options = null); - + /// /// Creates a webhook in this text channel. /// @@ -63,24 +63,25 @@ namespace Discord /// The avatar of the webhook. /// The options to be used when sending the request. /// - /// The created webhook. + /// An awaitable containing the created webhook. /// Task CreateWebhookAsync(string name, Stream avatar = null, RequestOptions options = null); /// - /// Gets the webhook in this text channel with the provided ID. + /// Gets a webhook available in this text channel. /// - /// The ID of the webhook. + /// The identifier of the webhook. /// The options to be used when sending the request. /// - /// A webhook associated with the , or null if not found. + /// An awaitable containing a webhook associated with the identifier; null if not + /// found. /// Task GetWebhookAsync(ulong id, RequestOptions options = null); /// - /// Gets the webhooks for this text channel. + /// Gets the webhooks available in this text channel. /// /// The options to be used when sending the request. /// - /// An awaitable containing a collection of webhooks. + /// An awaitable containing a collection of found webhooks. /// Task> GetWebhooksAsync(RequestOptions options = null); } diff --git a/src/Discord.Net.Core/Entities/IApplication.cs b/src/Discord.Net.Core/Entities/IApplication.cs index eb9fddd89..78a87dc19 100644 --- a/src/Discord.Net.Core/Entities/IApplication.cs +++ b/src/Discord.Net.Core/Entities/IApplication.cs @@ -19,7 +19,7 @@ namespace Discord string[] RPCOrigins { get; } ulong Flags { get; } /// - /// Gets the icon URL of the application. + /// Gets the icon URL of the application. /// string IconUrl { get; } diff --git a/src/Discord.Net.Core/Entities/Messages/EmbedFooter.cs b/src/Discord.Net.Core/Entities/Messages/EmbedFooter.cs index cd3839ac6..4c507d017 100644 --- a/src/Discord.Net.Core/Entities/Messages/EmbedFooter.cs +++ b/src/Discord.Net.Core/Entities/Messages/EmbedFooter.cs @@ -6,12 +6,27 @@ namespace Discord [DebuggerDisplay("{DebuggerDisplay,nq}")] public struct EmbedFooter { - /// Gets the text of the footer. - public string Text { get; internal set; } - /// Gets the icon URL of the footer. - public string IconUrl { get; internal set; } - /// Gets the proxified icon URL of the footer. - public string ProxyUrl { get; internal set; } + /// + /// Gets the text of the footer field. + /// + /// + /// A string containing the text of the footer field. + /// + public string Text { get; } + /// + /// Gets the URL of the footer icon. + /// + /// + /// A string containing the URL of the footer icon. + /// + public string IconUrl { get; } + /// + /// Gets the proxied URL of the footer icon link. + /// + /// + /// A string containing the proxied URL of the footer icon. + /// + public string ProxyUrl { get; } internal EmbedFooter(string text, string iconUrl, string proxyUrl) { @@ -21,6 +36,12 @@ namespace Discord } private string DebuggerDisplay => $"{Text} ({IconUrl})"; + /// + /// Gets the text of the footer field. + /// + /// + /// A string that resolves to . + /// public override string ToString() => Text; } } diff --git a/src/Discord.Net.Core/Entities/Messages/EmbedImage.cs b/src/Discord.Net.Core/Entities/Messages/EmbedImage.cs index b71e77721..9ce2bfe73 100644 --- a/src/Discord.Net.Core/Entities/Messages/EmbedImage.cs +++ b/src/Discord.Net.Core/Entities/Messages/EmbedImage.cs @@ -6,13 +6,35 @@ namespace Discord [DebuggerDisplay("{DebuggerDisplay,nq}")] public struct EmbedImage { - /// Gets the URL of the image. + /// + /// Gets the URL of the image. + /// + /// + /// A string containing the URL of the image. + /// public string Url { get; } - /// Gets the proxified URL of the image. + /// + /// Gets a proxied URL of this image. + /// + /// + /// A string containing the proxied URL of this image. + /// public string ProxyUrl { get; } - /// Gets the height of the image if any is set. + /// + /// Gets the height of this image. + /// + /// + /// A representing the height of this image if it can be retrieved; otherwise + /// null. + /// public int? Height { get; } - /// Gets the width of the image if any is set. + /// + /// Gets the width of this image. + /// + /// + /// A representing the width of this image if it can be retrieved; otherwise + /// null. + /// public int? Width { get; } internal EmbedImage(string url, string proxyUrl, int? height, int? width) @@ -24,6 +46,12 @@ namespace Discord } private string DebuggerDisplay => $"{Url} ({(Width != null && Height != null ? $"{Width}x{Height}" : "0x0")})"; - public override string ToString() => Url.ToString(); + /// + /// Gets the URL of the thumbnail. + /// + /// + /// A string that resolves to . + /// + public override string ToString() => Url; } } diff --git a/src/Discord.Net.Core/Entities/Messages/EmbedProvider.cs b/src/Discord.Net.Core/Entities/Messages/EmbedProvider.cs index 365f6b85f..960fb3d78 100644 --- a/src/Discord.Net.Core/Entities/Messages/EmbedProvider.cs +++ b/src/Discord.Net.Core/Entities/Messages/EmbedProvider.cs @@ -6,9 +6,19 @@ namespace Discord [DebuggerDisplay("{DebuggerDisplay,nq}")] public struct EmbedProvider { - /// Gets the name of the provider. + /// + /// Gets the name of the provider. + /// + /// + /// A string representing the name of the provider. + /// public string Name { get; } - /// Gets the URL of the provider. + /// + /// Gets the URL of the provider. + /// + /// + /// A string representing the link to the provider. + /// public string Url { get; } internal EmbedProvider(string name, string url) @@ -18,6 +28,12 @@ namespace Discord } private string DebuggerDisplay => $"{Name} ({Url})"; + /// + /// Gets the name of the provider. + /// + /// + /// A string that resolves to . + /// public override string ToString() => Name; } } diff --git a/src/Discord.Net.Core/Entities/Messages/EmbedThumbnail.cs b/src/Discord.Net.Core/Entities/Messages/EmbedThumbnail.cs index 3d00cfb2e..7f7b582dc 100644 --- a/src/Discord.Net.Core/Entities/Messages/EmbedThumbnail.cs +++ b/src/Discord.Net.Core/Entities/Messages/EmbedThumbnail.cs @@ -6,13 +6,35 @@ namespace Discord [DebuggerDisplay("{DebuggerDisplay,nq}")] public struct EmbedThumbnail { - /// Gets the URL of the thumbnail. + /// + /// Gets the URL of the thumbnail. + /// + /// + /// A string containing the URL of the thumbnail. + /// public string Url { get; } - /// Gets the proxified URL of the thumbnail. + /// + /// Gets a proxied URL of this thumbnail. + /// + /// + /// A string containing the proxied URL of this thumbnail. + /// public string ProxyUrl { get; } - /// Gets the height of the thumbnail if any is set. + /// + /// Gets the height of this thumbnail. + /// + /// + /// A representing the height of this thumbnail if it can be retrieved; otherwise + /// null. + /// public int? Height { get; } - /// Gets the width of the thumbnail if any is set. + /// + /// Gets the width of this thumbnail. + /// + /// + /// A representing the width of this thumbnail if it can be retrieved; otherwise + /// null. + /// public int? Width { get; } internal EmbedThumbnail(string url, string proxyUrl, int? height, int? width) @@ -24,6 +46,12 @@ namespace Discord } private string DebuggerDisplay => $"{Url} ({(Width != null && Height != null ? $"{Width}x{Height}" : "0x0")})"; - public override string ToString() => Url.ToString(); + /// + /// Gets the URL of the thumbnail. + /// + /// + /// A string that resolves to . + /// + public override string ToString() => Url; } } diff --git a/src/Discord.Net.Core/Entities/Messages/IUserMessage.cs b/src/Discord.Net.Core/Entities/Messages/IUserMessage.cs index bad4e36c7..2ea8a02a7 100644 --- a/src/Discord.Net.Core/Entities/Messages/IUserMessage.cs +++ b/src/Discord.Net.Core/Entities/Messages/IUserMessage.cs @@ -12,32 +12,75 @@ namespace Discord /// /// Modifies this message. /// + /// + /// + /// await msg.ModifyAsync(x => x.Content = "Hello World!"); + /// + /// + /// A delegate containing the properties to modify the message with. + /// The options to be used when sending the request. + /// + /// An awaitable . + /// Task ModifyAsync(Action func, RequestOptions options = null); /// /// Adds this message to its channel's pinned messages. /// + /// The options to be used when sending the request. + /// + /// An awaitable . + /// Task PinAsync(RequestOptions options = null); /// /// Removes this message from its channel's pinned messages. /// + /// The options to be used when sending the request. + /// + /// An awaitable . + /// Task UnpinAsync(RequestOptions options = null); /// - /// Returns all reactions included in this message. + /// Gets all reactions included in this message. /// IReadOnlyDictionary Reactions { get; } /// /// Adds a reaction to this message. /// + /// + /// + /// await msg.AddReactionAsync(new Emoji("\U0001f495")); + /// + /// + /// The emoji used to react to this message. + /// The options to be used when sending the request. + /// + /// An awaitable . + /// Task AddReactionAsync(IEmote emote, RequestOptions options = null); /// /// Removes a reaction from message. /// + /// + /// + /// await msg.RemoveReactionAsync(new Emoji("\U0001f495"), msg.Author); + /// + /// + /// The emoji used to react to this message. + /// The user that added the emoji. + /// The options to be used when sending the request. + /// + /// An awaitable . + /// Task RemoveReactionAsync(IEmote emote, IUser user, RequestOptions options = null); /// /// Removes all reactions from this message. /// + /// The options to be used when sending the request. + /// + /// An awaitable . + /// Task RemoveAllReactionsAsync(RequestOptions options = null); /// /// Gets all users that reacted to a message with a given emote. @@ -47,6 +90,11 @@ namespace Discord /// /// Transforms this message's text into a human-readable form by resolving its tags. /// + /// Determines how the user tag should be handled. + /// Determines how the channel tag should be handled. + /// Determines how the role tag should be handled. + /// Determines how the @everyone tag should be handled. + /// Determines how the emoji tag should be handled. string Resolve( TagHandling userHandling = TagHandling.Name, TagHandling channelHandling = TagHandling.Name, diff --git a/src/Discord.Net.Core/Entities/Roles/IRole.cs b/src/Discord.Net.Core/Entities/Roles/IRole.cs index 8dde78c11..1fb2732ce 100644 --- a/src/Discord.Net.Core/Entities/Roles/IRole.cs +++ b/src/Discord.Net.Core/Entities/Roles/IRole.cs @@ -4,12 +4,12 @@ using System.Threading.Tasks; namespace Discord { /// - /// Represents a generic role object. + /// Represents a generic role object to be given to a guild user. /// public interface IRole : ISnowflakeEntity, IDeletable, IMentionable, IComparable { /// - /// Gets the guild owning this role. + /// Gets the guild that owns this role. /// /// /// A guild representing the parent guild of this role. diff --git a/src/Discord.Net.Core/Entities/Users/IPresence.cs b/src/Discord.Net.Core/Entities/Users/IPresence.cs index d40d47251..b300115f8 100644 --- a/src/Discord.Net.Core/Entities/Users/IPresence.cs +++ b/src/Discord.Net.Core/Entities/Users/IPresence.cs @@ -1,7 +1,7 @@ namespace Discord { /// - /// Represents a Discord user's presence status. + /// Represents the user's presence status. This may include their online status and their activity. /// public interface IPresence { diff --git a/src/Discord.Net.Core/Logging/LogMessage.cs b/src/Discord.Net.Core/Logging/LogMessage.cs index d70bb01f5..715cac677 100644 --- a/src/Discord.Net.Core/Logging/LogMessage.cs +++ b/src/Discord.Net.Core/Logging/LogMessage.cs @@ -4,29 +4,41 @@ using System.Text; namespace Discord { /// - /// Represents a message used for logging purposes. + /// Provides a message object used for logging purposes. /// public struct LogMessage { /// - /// Gets the severity of the log message. + /// Gets the severity of the log entry. /// + /// + /// A enum to indicate the severeness of the incident or event. + /// public LogSeverity Severity { get; } /// - /// Gets the source of the log message. + /// Gets the source of the log entry. /// + /// + /// A string representing the source of the log entry. + /// public string Source { get; } /// - /// Gets the message of the log message. + /// Gets the message of this log entry. /// + /// + /// A string containing the message of this log entry. + /// public string Message { get; } /// - /// Gets the exception of the log message. + /// Gets the exception of this log entry. /// + /// + /// An object associated with an incident; otherwise null. + /// public Exception Exception { get; } /// - /// Initializes a new struct with the severity, source, message of the event, and + /// Initializes a new struct with the severity, source, message of the event, and /// optionally, an exception. /// /// The severity of the event. diff --git a/src/Discord.Net.Core/RequestOptions.cs b/src/Discord.Net.Core/RequestOptions.cs index 47cb8be70..47a6b5054 100644 --- a/src/Discord.Net.Core/RequestOptions.cs +++ b/src/Discord.Net.Core/RequestOptions.cs @@ -13,11 +13,23 @@ namespace Discord public static RequestOptions Default => new RequestOptions(); /// - /// Gets or set 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 sets the maximum time to wait for for this request to complete. /// + /// + /// Gets or set the max time, in milliseconds, to wait for 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. + /// + /// + /// A in milliseconds for when the request times out. + /// public int? Timeout { get; set; } + /// + /// Gets or sets the cancellation token for this request. + /// + /// + /// A for this request. + /// public CancellationToken CancelToken { get; set; } = CancellationToken.None; /// /// Gets or sets the retry behavior when the request fails. diff --git a/src/Discord.Net.Core/Utils/DateTimeUtils.cs b/src/Discord.Net.Core/Utils/DateTimeUtils.cs index e2a8faa75..608476889 100644 --- a/src/Discord.Net.Core/Utils/DateTimeUtils.cs +++ b/src/Discord.Net.Core/Utils/DateTimeUtils.cs @@ -2,13 +2,12 @@ using System; namespace Discord { - //Source: https://github.com/dotnet/coreclr/blob/master/src/mscorlib/src/System/DateTimeOffset.cs + /// internal static class DateTimeUtils { public static DateTimeOffset FromTicks(long ticks) => new DateTimeOffset(ticks, TimeSpan.Zero); public static DateTimeOffset? FromTicks(long? ticks) => ticks != null ? new DateTimeOffset(ticks.Value, TimeSpan.Zero) : (DateTimeOffset?)null; - } } diff --git a/src/Discord.Net.Core/Utils/MentionUtils.cs b/src/Discord.Net.Core/Utils/MentionUtils.cs index ae506e142..7e6b22619 100644 --- a/src/Discord.Net.Core/Utils/MentionUtils.cs +++ b/src/Discord.Net.Core/Utils/MentionUtils.cs @@ -5,7 +5,7 @@ using System.Text; namespace Discord { /// - /// Represents a helper class for mention-related parsing. + /// Provides a series of helper methods for parsing mentions. /// public static class MentionUtils { diff --git a/src/Discord.Net.Core/Utils/SnowflakeUtils.cs b/src/Discord.Net.Core/Utils/SnowflakeUtils.cs index eecebfb24..dd8f8ca66 100644 --- a/src/Discord.Net.Core/Utils/SnowflakeUtils.cs +++ b/src/Discord.Net.Core/Utils/SnowflakeUtils.cs @@ -2,10 +2,27 @@ using System; namespace Discord { + /// + /// Provides a series of helper methods for handling snowflake identifiers. + /// public static class SnowflakeUtils { + /// + /// Resolves the time of which the snowflake is generated. + /// + /// The snowflake identifier to resolve. + /// + /// A representing the time for when the object is geenrated. + /// public static DateTimeOffset FromSnowflake(ulong value) => DateTimeOffset.FromUnixTimeMilliseconds((long)((value >> 22) + 1420070400000UL)); + /// + /// Generates a pseudo-snowflake identifier with a . + /// + /// The time to be used in the new snowflake. + /// + /// A representing the newly generated snowflake identifier. + /// public static ulong ToSnowflake(DateTimeOffset value) => ((ulong)value.ToUnixTimeMilliseconds() - 1420070400000UL) << 22; } diff --git a/src/Discord.Net.WebSocket/Entities/Channels/SocketDMChannel.cs b/src/Discord.Net.WebSocket/Entities/Channels/SocketDMChannel.cs index c6edbcbb7..7f3f92150 100644 --- a/src/Discord.Net.WebSocket/Entities/Channels/SocketDMChannel.cs +++ b/src/Discord.Net.WebSocket/Entities/Channels/SocketDMChannel.cs @@ -3,6 +3,7 @@ using System; using System.Collections.Generic; using System.Collections.Immutable; using System.Diagnostics; +using System.Diagnostics.CodeAnalysis; using System.IO; using System.Linq; using System.Threading.Tasks; diff --git a/src/Discord.Net.WebSocket/Entities/Channels/SocketTextChannel.cs b/src/Discord.Net.WebSocket/Entities/Channels/SocketTextChannel.cs index 5909421d5..f77dedb3e 100644 --- a/src/Discord.Net.WebSocket/Entities/Channels/SocketTextChannel.cs +++ b/src/Discord.Net.WebSocket/Entities/Channels/SocketTextChannel.cs @@ -20,7 +20,14 @@ namespace Discord.WebSocket /// public string Topic { get; private set; } + /// public ulong? CategoryId { get; private set; } + /// + /// Gets the parent (category) of this channel in the guild's channel list. + /// + /// + /// An representing the parent of this channel; null if none is set. + /// public ICategoryChannel Category => CategoryId.HasValue ? Guild.GetChannel(CategoryId.Value) as ICategoryChannel : null; @@ -66,6 +73,15 @@ namespace Discord.WebSocket /// public SocketMessage GetCachedMessage(ulong id) => _messages?.Get(id); + /// + /// Gets a message from this message channel. + /// + /// The ID of the message. + /// The options to be used when sending the request. + /// + /// An awaitable containing the downloaded message; null if none is found or if + /// the message fails to be retrieved. + /// public async Task GetMessageAsync(ulong id, RequestOptions options = null) { IMessage msg = _messages?.Get(id); @@ -73,10 +89,41 @@ namespace Discord.WebSocket msg = await ChannelHelper.GetMessageAsync(this, Discord, id, options).ConfigureAwait(false); return msg; } + /// + /// Gets the last N messages from this message channel. + /// + /// The numbers of message to be gotten from. + /// The options to be used when sending the request. + /// + /// Paged collection of messages. Flattening the paginated response into a collection of messages with + /// is required if you wish to access the messages. + /// public IAsyncEnumerable> GetMessagesAsync(int limit = DiscordConfig.MaxMessagesPerBatch, RequestOptions options = null) => SocketChannelHelper.GetMessagesAsync(this, Discord, _messages, null, Direction.Before, limit, CacheMode.AllowDownload, options); + /// + /// Gets a collection of messages in this channel. + /// + /// The ID of the starting message to get the messages from. + /// The direction of the messages to be gotten from. + /// The numbers of message to be gotten from. + /// The options to be used when sending the request. + /// + /// Paged collection of messages. Flattening the paginated response into a collection of messages with + /// is required if you wish to access the messages. + /// public IAsyncEnumerable> GetMessagesAsync(ulong fromMessageId, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch, RequestOptions options = null) => SocketChannelHelper.GetMessagesAsync(this, Discord, _messages, fromMessageId, dir, limit, CacheMode.AllowDownload, options); + /// + /// Gets a collection of messages in this channel. + /// + /// The starting message to get the messages from. + /// The direction of the messages to be gotten from. + /// The numbers of message to be gotten from. + /// The options to be used when sending the request. + /// + /// Paged collection of messages. Flattening the paginated response into a collection of messages with + /// is required if you wish to access the messages. + /// public IAsyncEnumerable> GetMessagesAsync(IMessage fromMessage, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch, RequestOptions options = null) => SocketChannelHelper.GetMessagesAsync(this, Discord, _messages, fromMessage.Id, dir, limit, CacheMode.AllowDownload, options); /// @@ -93,13 +140,16 @@ namespace Discord.WebSocket => ChannelHelper.GetPinnedMessagesAsync(this, Discord, options); /// + /// Message content is too long, length must be less or equal to . public Task SendMessageAsync(string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null) => ChannelHelper.SendMessageAsync(this, Discord, text, isTTS, embed, options); /// public Task SendFileAsync(string filePath, string text, bool isTTS = false, Embed embed = null, RequestOptions options = null) => ChannelHelper.SendFileAsync(this, Discord, filePath, text, isTTS, embed, options); + /// + /// Message content is too long, length must be less or equal to . public Task SendFileAsync(Stream stream, string filename, string text, bool isTTS = false, Embed embed = null, RequestOptions options = null) => ChannelHelper.SendFileAsync(this, Discord, stream, filename, text, isTTS, embed, options); @@ -110,8 +160,10 @@ namespace Discord.WebSocket public Task DeleteMessagesAsync(IEnumerable messageIds, RequestOptions options = null) => ChannelHelper.DeleteMessagesAsync(this, Discord, messageIds, options); + /// public Task DeleteMessageAsync(ulong messageId, RequestOptions options = null) => ChannelHelper.DeleteMessageAsync(this, messageId, Discord, options); + /// public Task DeleteMessageAsync(IMessage message, RequestOptions options = null) => ChannelHelper.DeleteMessageAsync(this, message.Id, Discord, options); @@ -150,7 +202,7 @@ namespace Discord.WebSocket /// The avatar of the webhook. /// The options to be used when sending the request. /// - /// The created webhook. + /// An awaitable containing the created webhook. /// public Task CreateWebhookAsync(string name, Stream avatar = null, RequestOptions options = null) => ChannelHelper.CreateWebhookAsync(this, Discord, name, avatar, options); @@ -160,7 +212,8 @@ namespace Discord.WebSocket /// The identifier of the webhook. /// The options to be used when sending the request. /// - /// An awaitable webhook associated with the identifier, or null if not found. + /// An awaitable containing a webhook associated with the identifier; null if not + /// found. /// public Task GetWebhookAsync(ulong id, RequestOptions options = null) => ChannelHelper.GetWebhookAsync(this, Discord, id, options); @@ -169,7 +222,7 @@ namespace Discord.WebSocket /// /// The options to be used when sending the request. /// - /// An awaitable collection of webhooks. + /// An awaitable containing a collection of found webhooks. /// public Task> GetWebhooksAsync(RequestOptions options = null) => ChannelHelper.GetWebhooksAsync(this, Discord, options); @@ -229,6 +282,7 @@ namespace Discord.WebSocket => await SendMessageAsync(text, isTTS, embed, options).ConfigureAwait(false); // INestedChannel + /// Task INestedChannel.GetCategoryAsync(CacheMode mode, RequestOptions options) => Task.FromResult(Category); } diff --git a/src/Discord.Net.WebSocket/Entities/Channels/SocketVoiceChannel.cs b/src/Discord.Net.WebSocket/Entities/Channels/SocketVoiceChannel.cs index 10bdfdb56..3d466aff5 100644 --- a/src/Discord.Net.WebSocket/Entities/Channels/SocketVoiceChannel.cs +++ b/src/Discord.Net.WebSocket/Entities/Channels/SocketVoiceChannel.cs @@ -20,7 +20,14 @@ namespace Discord.WebSocket public int Bitrate { get; private set; } /// public int? UserLimit { get; private set; } + /// public ulong? CategoryId { get; private set; } + /// + /// Gets the parent (category) of this channel in the guild's channel list. + /// + /// + /// An representing the parent of this channel; null if none is set. + /// public ICategoryChannel Category => CategoryId.HasValue ? Guild.GetChannel(CategoryId.Value) as ICategoryChannel : null; @@ -56,6 +63,12 @@ namespace Discord.WebSocket return await Guild.ConnectAudioAsync(Id, selfDeaf, selfMute, external).ConfigureAwait(false); } + /// + /// Disconnects from this voice channel if the client is in an active voice connection. + /// + /// + /// An awaitable . + /// public async Task DisconnectAsync() => await Guild.DisconnectAudioAsync(); @@ -80,6 +93,7 @@ namespace Discord.WebSocket => ImmutableArray.Create>(Users).ToAsyncEnumerable(); // INestedChannel + /// Task INestedChannel.GetCategoryAsync(CacheMode mode, RequestOptions options) => Task.FromResult(Category); } diff --git a/src/Discord.Net.WebSocket/Entities/Guilds/SocketGuild.cs b/src/Discord.Net.WebSocket/Entities/Guilds/SocketGuild.cs index fef0c2f90..302935b80 100644 --- a/src/Discord.Net.WebSocket/Entities/Guilds/SocketGuild.cs +++ b/src/Discord.Net.WebSocket/Entities/Guilds/SocketGuild.cs @@ -415,8 +415,26 @@ namespace Discord.WebSocket /// public Task> GetBansAsync(RequestOptions options = null) => GuildHelper.GetBansAsync(this, Discord, options); + /// + /// Gets a ban object for a banned user. + /// + /// The banned user. + /// The options to be used when sending the request. + /// + /// An awaitable containing a REST-based ban object, which contains the user information + /// and the reason for the ban; null if the ban entry cannot be found. + /// public Task GetBanAsync(IUser user, RequestOptions options = null) => GuildHelper.GetBanAsync(this, Discord, user.Id, options); + /// + /// Gets a ban object for a banned user. + /// + /// The snowflake identifier for the banned user. + /// The options to be used when sending the request. + /// + /// An awaitable containing a REST-based ban object, which contains the user information + /// and the reason for the ban; null if the ban entry cannot be found. + /// public Task GetBanAsync(ulong userId, RequestOptions options = null) => GuildHelper.GetBanAsync(this, Discord, userId, options); @@ -895,6 +913,9 @@ namespace Discord.WebSocket /// /// Gets the name of the guild. /// + /// + /// A string that resolves to the of this guild. + /// public override string ToString() => Name; private string DebuggerDisplay => $"{Name} ({Id})"; internal SocketGuild Clone() => MemberwiseClone() as SocketGuild; diff --git a/src/Discord.Net.WebSocket/Entities/Roles/SocketRole.cs b/src/Discord.Net.WebSocket/Entities/Roles/SocketRole.cs index 14af11e07..b5e26ad78 100644 --- a/src/Discord.Net.WebSocket/Entities/Roles/SocketRole.cs +++ b/src/Discord.Net.WebSocket/Entities/Roles/SocketRole.cs @@ -8,9 +8,18 @@ using Model = Discord.API.Role; namespace Discord.WebSocket { + /// + /// Represents a WebSocket-based role to be given to a guild user. + /// [DebuggerDisplay(@"{DebuggerDisplay,nq}")] public class SocketRole : SocketEntity, IRole { + /// + /// Gets the guild that owns this role. + /// + /// + /// A representing the parent guild of this role. + /// public SocketGuild Guild { get; } /// @@ -30,6 +39,12 @@ namespace Discord.WebSocket /// public DateTimeOffset CreatedAt => SnowflakeUtils.FromSnowflake(Id); + /// + /// Returns a value that determines if the role is an @everyone role. + /// + /// + /// true if the role is @everyone; otherwise false. + /// public bool IsEveryone => Id == Guild.Id; /// public string Mention => IsEveryone ? "@everyone" : MentionUtils.MentionRole(Id); @@ -65,6 +80,12 @@ namespace Discord.WebSocket public Task DeleteAsync(RequestOptions options = null) => RoleHelper.DeleteAsync(this, Discord, options); + /// + /// Gets the name of the role. + /// + /// + /// A string that resolves to . + /// public override string ToString() => Name; private string DebuggerDisplay => $"{Name} ({Id})"; internal SocketRole Clone() => MemberwiseClone() as SocketRole; diff --git a/src/Discord.Net.WebSocket/Entities/Users/SocketGroupUser.cs b/src/Discord.Net.WebSocket/Entities/Users/SocketGroupUser.cs index 601677e2e..f560aadbb 100644 --- a/src/Discord.Net.WebSocket/Entities/Users/SocketGroupUser.cs +++ b/src/Discord.Net.WebSocket/Entities/Users/SocketGroupUser.cs @@ -6,7 +6,14 @@ namespace Discord.WebSocket [DebuggerDisplay("{DebuggerDisplay,nq}")] public class SocketGroupUser : SocketUser, IGroupUser { + /// + /// Gets the group channel of the user. + /// + /// + /// A representing the channel of which the user belongs to. + /// public SocketGroupChannel Channel { get; } + /// internal override SocketGlobalUser GlobalUser { get; } /// @@ -17,6 +24,7 @@ namespace Discord.WebSocket public override ushort DiscriminatorValue { get { return GlobalUser.DiscriminatorValue; } internal set { GlobalUser.DiscriminatorValue = value; } } /// public override string AvatarId { get { return GlobalUser.AvatarId; } internal set { GlobalUser.AvatarId = value; } } + /// internal override SocketPresence Presence { get { return GlobalUser.Presence; } set { GlobalUser.Presence = value; } } /// diff --git a/src/Discord.Net.WebSocket/Entities/Users/SocketPresence.cs b/src/Discord.Net.WebSocket/Entities/Users/SocketPresence.cs index 8942bdf32..4112fd273 100644 --- a/src/Discord.Net.WebSocket/Entities/Users/SocketPresence.cs +++ b/src/Discord.Net.WebSocket/Entities/Users/SocketPresence.cs @@ -3,6 +3,9 @@ using Model = Discord.API.Presence; namespace Discord.WebSocket { + /// + /// Represents the WebSocket user's presence status. This may include their online status and their activity. + /// [DebuggerDisplay(@"{DebuggerDisplay,nq}")] public struct SocketPresence : IPresence { @@ -21,6 +24,12 @@ namespace Discord.WebSocket return new SocketPresence(model.Status, model.Game?.ToEntity()); } + /// + /// Gets the status of the user. + /// + /// + /// A string that resolves to . + /// public override string ToString() => Status.ToString(); private string DebuggerDisplay => $"{Status}{(Activity != null ? $", {Activity.Name}": "")}"; diff --git a/src/Discord.Net.WebSocket/Entities/Users/SocketSelfUser.cs b/src/Discord.Net.WebSocket/Entities/Users/SocketSelfUser.cs index af7710629..efbddd57b 100644 --- a/src/Discord.Net.WebSocket/Entities/Users/SocketSelfUser.cs +++ b/src/Discord.Net.WebSocket/Entities/Users/SocketSelfUser.cs @@ -6,6 +6,9 @@ using Model = Discord.API.User; namespace Discord.WebSocket { + /// + /// Represents the logged-in WebSocker-based user. + /// [DebuggerDisplay(@"{DebuggerDisplay,nq}")] public class SocketSelfUser : SocketUser, ISelfUser { diff --git a/src/Discord.Net.WebSocket/Entities/Users/SocketUnknownUser.cs b/src/Discord.Net.WebSocket/Entities/Users/SocketUnknownUser.cs index b3eb08f6d..e6ce0137e 100644 --- a/src/Discord.Net.WebSocket/Entities/Users/SocketUnknownUser.cs +++ b/src/Discord.Net.WebSocket/Entities/Users/SocketUnknownUser.cs @@ -4,17 +4,30 @@ using Model = Discord.API.User; namespace Discord.WebSocket { + /// + /// Represents a WebSocket-based user that is yet to be recognized by the client. + /// + /// + /// A user may not be recognized due to the user missing from the cache or failed to be recognized properly. + /// [DebuggerDisplay(@"{DebuggerDisplay,nq}")] public class SocketUnknownUser : SocketUser { + /// public override string Username { get; internal set; } + /// public override ushort DiscriminatorValue { get; internal set; } + /// public override string AvatarId { get; internal set; } + /// public override bool IsBot { get; internal set; } - + + /// public override bool IsWebhook => false; internal override SocketPresence Presence { get { return new SocketPresence(UserStatus.Offline, null); } set { } } + /// + /// This field is not supported for an unknown user. internal override SocketGlobalUser GlobalUser => throw new NotSupportedException(); diff --git a/src/Discord.Net.WebSocket/Entities/Users/SocketVoiceState.cs b/src/Discord.Net.WebSocket/Entities/Users/SocketVoiceState.cs index d5f0433ad..3e5d1c3b7 100644 --- a/src/Discord.Net.WebSocket/Entities/Users/SocketVoiceState.cs +++ b/src/Discord.Net.WebSocket/Entities/Users/SocketVoiceState.cs @@ -4,9 +4,15 @@ using Model = Discord.API.VoiceState; namespace Discord.WebSocket { + /// + /// Represents a WebSocket user's voice connection status. + /// [DebuggerDisplay(@"{DebuggerDisplay,nq}")] public struct SocketVoiceState : IVoiceState { + /// + /// Initializes a default with everything set to null or false. + /// public static readonly SocketVoiceState Default = new SocketVoiceState(null, null, false, false, false, false, false); [Flags] @@ -64,15 +70,16 @@ namespace Discord.WebSocket } /// - /// Gets the name of the voice channel. + /// Gets the name of this voice channel. /// /// - /// The name of the voice channel. + /// A string that resolves to name of this voice channel; otherwise "Unknown". /// public override string ToString() => VoiceChannel?.Name ?? "Unknown"; private string DebuggerDisplay => $"{VoiceChannel?.Name ?? "Unknown"} ({_voiceStates})"; internal SocketVoiceState Clone() => this; + /// IVoiceChannel IVoiceState.VoiceChannel => VoiceChannel; } }