diff --git a/src/Discord.Net.Core/Entities/Channels/GuildChannelProperties.cs b/src/Discord.Net.Core/Entities/Channels/GuildChannelProperties.cs index a0edfc796..4e92a2369 100644 --- a/src/Discord.Net.Core/Entities/Channels/GuildChannelProperties.cs +++ b/src/Discord.Net.Core/Entities/Channels/GuildChannelProperties.cs @@ -10,8 +10,11 @@ namespace Discord /// Gets or sets the channel to this name. /// /// - /// When modifying an , the - /// MUST be alphanumeric with dashes. It must match the following RegEx: [a-z0-9-_]{2,100} + /// This property defines the new name for this channel. + /// + /// When modifying an , the must be alphanumeric with + /// dashes. It must match the RegEx [a-z0-9-_]{2,100}. + /// /// public Optional Name { get; set; } /// diff --git a/src/Discord.Net.Core/Entities/Channels/IAudioChannel.cs b/src/Discord.Net.Core/Entities/Channels/IAudioChannel.cs index e6642d8b0..6d8ef2cd3 100644 --- a/src/Discord.Net.Core/Entities/Channels/IAudioChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IAudioChannel.cs @@ -12,9 +12,21 @@ namespace Discord /// /// Connects to this audio channel. /// + /// Determines whether the client should deaf itself upon connection. + /// Determines whether the client should mute itself upon connection. + /// Determines whether the audio client is an external one or not. + /// + /// A task representing the asynchronous connection operation. The task result contains the + /// responsible for the connection. + /// Task ConnectAsync(bool selfDeaf = false, bool selfMute = false, bool external = false); - /// Disconnects from this audio channel. + /// + /// Disconnects from this audio channel. + /// + /// + /// A task representing the asynchronous disconnection operation. + /// Task DisconnectAsync(); } } diff --git a/src/Discord.Net.Core/Entities/Channels/IChannel.cs b/src/Discord.Net.Core/Entities/Channels/IChannel.cs index 04408989b..b66f778fb 100644 --- a/src/Discord.Net.Core/Entities/Channels/IChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IChannel.cs @@ -31,11 +31,12 @@ namespace Discord /// /// Gets a user in this channel. /// - /// The snowflake identifier of the user (e.g. 168693960628371456). - /// The that determines whether the object should be fetched from cache. + /// The snowflake identifier of the user (e.g. 168693960628371456). + /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing a user object that represents the user. + /// A task that represents the asynchronous get operation. The task result contains a user object that + /// represents the found user; null if none is found. /// Task GetUserAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); } diff --git a/src/Discord.Net.Core/Entities/Channels/IDMChannel.cs b/src/Discord.Net.Core/Entities/Channels/IDMChannel.cs index 49e58038a..f0ef7f3f3 100644 --- a/src/Discord.Net.Core/Entities/Channels/IDMChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IDMChannel.cs @@ -10,12 +10,18 @@ namespace Discord /// /// Gets the recipient of all messages in this channel. /// + /// + /// A user object that represents the other user in this channel. + /// IUser Recipient { get; } /// /// Closes this private channel, removing it from your channel list. /// /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous close operation. + /// Task CloseAsync(RequestOptions options = null); } } diff --git a/src/Discord.Net.Core/Entities/Channels/IGroupChannel.cs b/src/Discord.Net.Core/Entities/Channels/IGroupChannel.cs index 8ee2b622c..77af3450e 100644 --- a/src/Discord.Net.Core/Entities/Channels/IGroupChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IGroupChannel.cs @@ -11,6 +11,9 @@ namespace Discord /// Leaves this group. /// /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous leave operation. + /// Task LeaveAsync(RequestOptions options = null); } } diff --git a/src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs b/src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs index 301737aa1..7c4dd8675 100644 --- a/src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs @@ -16,7 +16,8 @@ namespace Discord /// Gets the position of this channel. /// /// - /// The position of this channel in the guild's channel list, relative to others of the same type. + /// An representing the position of this channel in the guild's channel list relative to + /// others of the same type. /// int Position { get; } @@ -24,14 +25,15 @@ namespace Discord /// Gets the guild associated with this channel. /// /// - /// A guild that this channel belongs to. + /// A guild object that this channel belongs to. /// IGuild Guild { get; } /// /// Gets the guild ID associated with this channel. /// /// - /// A guild snowflake identifier for the guild that this channel belongs to. + /// An representing the guild snowflake identifier for the guild that this channel + /// belongs to. /// ulong GuildId { get; } /// @@ -45,25 +47,14 @@ namespace Discord /// /// Creates a new invite to this channel. /// - /// - /// The time (in seconds) until the invite expires. Set to null to never expire. - /// - /// - /// The max amount of times this invite may be used. Set to null to have unlimited uses. - /// - /// - /// If true, a user accepting this invite will be kicked from the guild after closing their client. - /// - /// - /// If true, don't try to reuse a similar invite (useful for creating many unique one time use - /// invites). - /// - /// - /// The options to be used when sending the request. - /// + /// The time (in seconds) until the invite expires. Set to null to never expire. + /// The max amount of times this invite may be used. Set to null to have unlimited uses. + /// If true, the user accepting this invite will be kicked from the guild after closing their client. + /// If true, don't try to reuse a similar invite (useful for creating many unique one time use invites). + /// The options to be used when sending the request. /// - /// An awaitable containing an invite metadata object containing information for the - /// created invite. + /// A task that represents the asynchronous invite creation operation. The task result contains an invite + /// metadata object containing information for the created invite. /// Task CreateInviteAsync(int? maxAge = 86400, int? maxUses = default(int?), bool isTemporary = false, bool isUnique = false, RequestOptions options = null); /// @@ -71,18 +62,18 @@ namespace Discord /// /// The options to be used when sending the request. /// - /// An awaitable containing a read-only collection of invite metadata that are created - /// for this channel. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection + /// of invite metadata that are created for this channel. /// Task> GetInvitesAsync(RequestOptions options = null); /// /// Modifies this guild channel. /// - /// The properties to modify the channel with. + /// The delegate containing the properties to modify the channel with. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task that represents the asynchronous modification operation. /// Task ModifyAsync(Action func, RequestOptions options = null); @@ -108,7 +99,7 @@ namespace Discord /// The role to remove the overwrite from. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task representing the asynchronous removal operation. /// Task RemovePermissionOverwriteAsync(IRole role, RequestOptions options = null); /// @@ -117,7 +108,7 @@ namespace Discord /// The user to remove the overwrite from. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task representing the asynchronous removal operation. /// Task RemovePermissionOverwriteAsync(IUser user, RequestOptions options = null); @@ -128,7 +119,7 @@ namespace Discord /// The overwrite to add to the role. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task representing the asynchronous permission addition operation. /// Task AddPermissionOverwriteAsync(IRole role, OverwritePermissions permissions, RequestOptions options = null); /// @@ -138,7 +129,7 @@ namespace Discord /// The overwrite to add to the user. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task representing the asynchronous permission addition operation. /// Task AddPermissionOverwriteAsync(IUser user, OverwritePermissions permissions, RequestOptions options = null); @@ -159,12 +150,11 @@ namespace Discord /// Gets a user in this channel with the provided ID. /// /// The ID of the user. - /// - /// 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. /// - /// An awaitable containing a guild user object that represents the user. + /// A task representing the asynchrnous get operation. The task result contains a guild user object that + /// represents the user; null if none is found. /// new Task GetUserAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); } diff --git a/src/Discord.Net.Core/Entities/Channels/IMessageChannel.cs b/src/Discord.Net.Core/Entities/Channels/IMessageChannel.cs index 803e07ff6..ef62f5d4f 100644 --- a/src/Discord.Net.Core/Entities/Channels/IMessageChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IMessageChannel.cs @@ -14,57 +14,67 @@ namespace Discord /// Sends a message to this message channel. /// /// The message to be sent. - /// Whether the message should be read aloud by Discord or not. - /// The to be sent. + /// Determines 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. + /// A task that represents an asynchrnous send operation for delievering the message. The task result + /// contains the sent message. /// Task SendMessageAsync(string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null); /// /// Sends a file to this message channel with an optional caption. /// + /// + /// This method sends a file as if you are uploading an attachment directly from your Discord client. + /// + /// 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 + /// . + /// + /// /// 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 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. + /// A task that represents an asynchrnous send operation for delievering the message. The task result + /// contains the sent message. /// Task SendFileAsync(string filePath, string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null); /// /// Sends a file to this message channel with an optional caption. /// - /// The of the file to be sent. + /// + /// This method sends a file as if you are uploading an attachment directly from your Discord client. + /// + /// 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 + /// . + /// + /// + /// 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 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. + /// A task that represents an asynchrnous send operation for delievering the message. The task result + /// contains the sent message. /// 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 snowflake identifier of the message. /// 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. + /// A task that represents an asynchrnous get operation for retrieving the message. The task result contains + /// the retrieved message; null if no message is found with the specified identifier. /// Task GetMessageAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); @@ -94,7 +104,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. /// @@ -115,25 +124,45 @@ namespace Discord /// /// The options to be used when sending the request. /// - /// An awaitable Task containing a collection of messages. + /// A task that represents the asynchronous get operation for retrieving pinned messages in this channel. + /// The task result contains a collection of messages found in the pinned messages. /// Task> GetPinnedMessagesAsync(RequestOptions options = null); - /// Deletes a message based on the message ID in this channel. + /// + /// Deletes a message. + /// + /// The snowflake identifier of the message that would be removed. + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous removal operation. + /// Task DeleteMessageAsync(ulong messageId, RequestOptions options = null); /// Deletes a message based on the provided message in this channel. + /// The message that would be removed. + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous removal operation. + /// Task DeleteMessageAsync(IMessage message, RequestOptions options = null); /// /// Broadcasts the "user is typing" message to all users in this channel, lasting 10 seconds. /// /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous operation that triggers the broadcast. + /// Task TriggerTypingAsync(RequestOptions options = null); /// /// Continuously broadcasts the "user is typing" message to all users in this channel until the returned /// object is disposed. /// /// The options to be used when sending the request. + /// + /// A disposable object that, upon its disposal, will stop the client from broadcasting its typing state in + /// this channel. + /// IDisposable EnterTypingState(RequestOptions options = null); } } diff --git a/src/Discord.Net.Core/Entities/Channels/INestedChannel.cs b/src/Discord.Net.Core/Entities/Channels/INestedChannel.cs index 99a4e6cd5..c6fcba9de 100644 --- a/src/Discord.Net.Core/Entities/Channels/INestedChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/INestedChannel.cs @@ -11,7 +11,7 @@ namespace Discord /// Gets the parent (category) ID of this channel in the guild's channel list. /// /// - /// An representing the snowflake identifier of the parent of this channel; + /// A representing the snowflake identifier of the parent of this channel; /// null if none is set. /// ulong? CategoryId { get; } @@ -21,7 +21,8 @@ namespace Discord /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// A category channel representing the parent of this channel; null if none is set. + /// A task that represents the asynchrnous get operation. The task result contains the category channel + /// representing the parent of this channel; null if none is set. /// Task GetCategoryAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); } diff --git a/src/Discord.Net.Core/Entities/Channels/IPrivateChannel.cs b/src/Discord.Net.Core/Entities/Channels/IPrivateChannel.cs index 41b409141..cd2307c2d 100644 --- a/src/Discord.Net.Core/Entities/Channels/IPrivateChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IPrivateChannel.cs @@ -11,7 +11,7 @@ namespace Discord /// Gets the users that can access this channel. /// /// - /// A collection of users that can access this channel. + /// A read-only collection of users that can access this channel. /// IReadOnlyCollection Recipients { get; } } diff --git a/src/Discord.Net.Core/Entities/Channels/ITextChannel.cs b/src/Discord.Net.Core/Entities/Channels/ITextChannel.cs index a2dce09ec..e619c1735 100644 --- a/src/Discord.Net.Core/Entities/Channels/ITextChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/ITextChannel.cs @@ -14,7 +14,7 @@ namespace Discord /// Determines whether the channel is NSFW. /// /// - /// true if the channel has the NSFW flag enabled; otherwise, false. + /// true if the channel has the NSFW flag enabled; otherwise false. /// bool IsNsfw { get; } @@ -22,7 +22,7 @@ namespace Discord /// Gets the current topic for this text channel. /// /// - /// The topic set in the channel, or null if none is set. + /// A string representing the topic set in the channel; null if none is set. /// string Topic { get; } @@ -30,32 +30,44 @@ namespace Discord /// Bulk-deletes multiple messages. /// /// + /// This method attempts to remove the messages specified in bulk. /// - /// This method can only remove messages that are posted within 14 days! + /// Due to the limitation set by Discord, this method can only remove messages that are posted within 14 days! /// /// /// The messages to be bulk-deleted. /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous bulk-removal operation. + /// Task DeleteMessagesAsync(IEnumerable messages, RequestOptions options = null); /// /// Bulk-deletes multiple messages. /// /// + /// This method attempts to remove the messages specified in bulk. /// - /// This method can only remove messages that are posted within 14 days! + /// Due to the limitation set by Discord, this method can only remove messages that are posted within 14 days! /// /// - /// The IDs of the messages to be bulk-deleted. + /// The snowflake identifier of the messages to be bulk-deleted. /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous bulk-removal operation. + /// Task DeleteMessagesAsync(IEnumerable messageIds, RequestOptions options = null); /// /// Modifies this text channel. /// - /// The properties to modify the channel with. + /// The delegate containing the properties to modify the channel with. /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous modification operation. + /// + /// Task ModifyAsync(Action func, RequestOptions options = null); - + /// /// Creates a webhook in this text channel. /// @@ -63,24 +75,27 @@ namespace Discord /// The avatar of the webhook. /// The options to be used when sending the request. /// - /// The created webhook. + /// A task that represents the asynchronous creation operation. The task result contains the newly 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. + /// A task that represents the asynchronous get operation. The task result contains a webhook associated + /// with the identifier; null if the webhook is 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. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection + /// of webhooks that is available in this channel. /// Task> GetWebhooksAsync(RequestOptions options = null); } diff --git a/src/Discord.Net.Core/Entities/Channels/IVoiceChannel.cs b/src/Discord.Net.Core/Entities/Channels/IVoiceChannel.cs index 3119a5ae7..b222ca004 100644 --- a/src/Discord.Net.Core/Entities/Channels/IVoiceChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IVoiceChannel.cs @@ -9,13 +9,20 @@ namespace Discord public interface IVoiceChannel : INestedChannel, IAudioChannel { /// - /// Gets the bitrate, in bits per second, clients in this voice channel are requested to use. + /// Gets the bitrate that the clients in this voice channel are requested to use. /// + /// + /// An representing the bitrate (bps) that this voice channel defines and requests the + /// client(s) to use. + /// int Bitrate { get; } /// - /// Gets the max amount of users allowed to be connected to this channel at one time, or - /// null if none is set. + /// Gets the max number of users allowed to be connected to this channel at once. /// + /// + /// An representing the maxmimum number of users that are allowed to be connected to this + /// channel at once; null if a limit is not set. + /// int? UserLimit { get; } /// @@ -23,6 +30,10 @@ namespace Discord /// /// The properties to modify the channel with. /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous modification operation. + /// + /// Task ModifyAsync(Action func, RequestOptions options = null); } } diff --git a/src/Discord.Net.Core/Entities/Channels/ReorderChannelProperties.cs b/src/Discord.Net.Core/Entities/Channels/ReorderChannelProperties.cs index 55427aec7..903a2a047 100644 --- a/src/Discord.Net.Core/Entities/Channels/ReorderChannelProperties.cs +++ b/src/Discord.Net.Core/Entities/Channels/ReorderChannelProperties.cs @@ -1,7 +1,7 @@ namespace Discord { /// - /// Properties that are used to reorder an . + /// Provides properties that are used to reorder an . /// public class ReorderChannelProperties { @@ -20,7 +20,7 @@ namespace Discord /// public int Position { get; } - /// Creates a used to reorder a channel. + /// Initializes a new instance of the class used to reorder a channel. /// Sets the ID of the channel to apply this position to. /// Sets the new zero-based position of this channel. public ReorderChannelProperties(ulong id, int position) diff --git a/src/Discord.Net.Core/Entities/Channels/TextChannelProperties.cs b/src/Discord.Net.Core/Entities/Channels/TextChannelProperties.cs index 03b56b26c..471f74c7d 100644 --- a/src/Discord.Net.Core/Entities/Channels/TextChannelProperties.cs +++ b/src/Discord.Net.Core/Entities/Channels/TextChannelProperties.cs @@ -1,11 +1,9 @@ -using System; - namespace Discord { /// - /// Properties that are used to modify an with the specified changes. + /// Provides properties that are used to modify an with the specified changes. /// - /// + /// public class TextChannelProperties : GuildChannelProperties { /// diff --git a/src/Discord.Net.Core/Entities/Channels/VoiceChannelProperties.cs b/src/Discord.Net.Core/Entities/Channels/VoiceChannelProperties.cs index 46e8f8550..fb4d47800 100644 --- a/src/Discord.Net.Core/Entities/Channels/VoiceChannelProperties.cs +++ b/src/Discord.Net.Core/Entities/Channels/VoiceChannelProperties.cs @@ -1,7 +1,7 @@ namespace Discord { /// - /// Properties that are used to modify an with the specified changes. + /// Provides properties that are used to modify an with the specified changes. /// public class VoiceChannelProperties : GuildChannelProperties { diff --git a/src/Discord.Net.Core/Entities/Emotes/Emoji.cs b/src/Discord.Net.Core/Entities/Emotes/Emoji.cs index c7a2dc5eb..102abf7e2 100644 --- a/src/Discord.Net.Core/Entities/Emotes/Emoji.cs +++ b/src/Discord.Net.Core/Entities/Emotes/Emoji.cs @@ -12,10 +12,13 @@ namespace Discord /// /// Gets the Unicode representation of this emote. /// + /// + /// A string that resolves to . + /// public override string ToString() => Name; /// - /// Creates a Unicode emoji. + /// Initializes a new class with the provided Unicode. /// /// The pure UTF-8 encoding of an emoji. public Emoji(string unicode) diff --git a/src/Discord.Net.Core/Entities/Emotes/Emote.cs b/src/Discord.Net.Core/Entities/Emotes/Emote.cs index 32d49fede..d8a4d4088 100644 --- a/src/Discord.Net.Core/Entities/Emotes/Emote.cs +++ b/src/Discord.Net.Core/Entities/Emotes/Emote.cs @@ -17,14 +17,18 @@ namespace Discord /// /// Gets whether this emote is animated. /// + /// + /// A boolean that determines whether or not this emote is an animated one. + /// public bool Animated { get; } - /// - /// Gets the date when this emote is created. - /// + /// public DateTimeOffset CreatedAt => SnowflakeUtils.FromSnowflake(Id); /// /// Gets the image URL of this emote. /// + /// + /// A string that points to the URL of this emote. + /// public string Url => CDN.GetEmojiUrl(Id, Animated); internal Emote(ulong id, string name, bool animated) @@ -59,7 +63,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 (e.g. <:dab:277855270321782784>). /// An emote. /// Invalid emote format. public static Emote Parse(string text) @@ -99,6 +103,9 @@ namespace Discord /// /// Returns the raw representation of the emote. /// + /// + /// A string representing the raw presentation of the emote (e.g. <:thonkang:282745590985523200>). + /// public override string ToString() => $"<{(Animated ? "a" : "")}:{Name}:{Id}>"; } } diff --git a/src/Discord.Net.Core/Entities/Emotes/EmoteProperties.cs b/src/Discord.Net.Core/Entities/Emotes/EmoteProperties.cs index a52f81ca7..41679d2af 100644 --- a/src/Discord.Net.Core/Entities/Emotes/EmoteProperties.cs +++ b/src/Discord.Net.Core/Entities/Emotes/EmoteProperties.cs @@ -3,7 +3,7 @@ using System.Collections.Generic; namespace Discord { /// - /// Properties that are used to modify an with the specified changes. + /// Provides properties that are used to modify an with the specified changes. /// /// public class EmoteProperties diff --git a/src/Discord.Net.Core/Entities/Emotes/GuildEmote.cs b/src/Discord.Net.Core/Entities/Emotes/GuildEmote.cs index f734c3648..3e13b1364 100644 --- a/src/Discord.Net.Core/Entities/Emotes/GuildEmote.cs +++ b/src/Discord.Net.Core/Entities/Emotes/GuildEmote.cs @@ -10,16 +10,25 @@ namespace Discord public class GuildEmote : Emote { /// - /// Gets whether this emoji is managed. + /// Gets whether this emoji is managed by an integration. /// + /// + /// A boolean that determines whether or not this emote is managed by a Twitch integration. + /// public bool IsManaged { get; } /// /// Gets whether this emoji must be wrapped in colons. /// + /// + /// A boolean that determines whether or not this emote requires the use of colons in chat to be used. + /// public bool RequireColons { get; } /// - /// Gets the roles this emoji is whitelisted to. + /// Gets the roles that are allowed to use this emoji. /// + /// + /// A read-only list containing snowflake identifiers for roles that are allowed to use this emoji. + /// public IReadOnlyList RoleIds { get; } internal GuildEmote(ulong id, string name, bool animated, bool isManaged, bool requireColons, IReadOnlyList roleIds) : base(id, name, animated) diff --git a/src/Discord.Net.Core/Entities/Emotes/IEmote.cs b/src/Discord.Net.Core/Entities/Emotes/IEmote.cs index e39601852..9141e8537 100644 --- a/src/Discord.Net.Core/Entities/Emotes/IEmote.cs +++ b/src/Discord.Net.Core/Entities/Emotes/IEmote.cs @@ -8,6 +8,9 @@ namespace Discord /// /// Gets the display name or Unicode representation of this emote. /// + /// + /// A string representing the display name or the Unicode representation (e.g. 🤔) of this emote. + /// string Name { get; } } } diff --git a/src/Discord.Net.Core/Entities/Guilds/GuildEmbedProperties.cs b/src/Discord.Net.Core/Entities/Guilds/GuildEmbedProperties.cs index 2977cd10c..34473e93c 100644 --- a/src/Discord.Net.Core/Entities/Guilds/GuildEmbedProperties.cs +++ b/src/Discord.Net.Core/Entities/Guilds/GuildEmbedProperties.cs @@ -1,7 +1,7 @@ namespace Discord { /// - /// Properties that are used to modify the widget of an with the specified changes. + /// Provides properties that are used to modify the widget of an with the specified changes. /// public class GuildEmbedProperties { diff --git a/src/Discord.Net.Core/Entities/Guilds/GuildIntegrationProperties.cs b/src/Discord.Net.Core/Entities/Guilds/GuildIntegrationProperties.cs index c8b5b3072..2ca19b50a 100644 --- a/src/Discord.Net.Core/Entities/Guilds/GuildIntegrationProperties.cs +++ b/src/Discord.Net.Core/Entities/Guilds/GuildIntegrationProperties.cs @@ -1,7 +1,7 @@ namespace Discord { /// - /// Properties used to modify an with the specified changes. + /// Provides properties used to modify an with the specified changes. /// public class GuildIntegrationProperties { diff --git a/src/Discord.Net.Core/Entities/Guilds/GuildProperties.cs b/src/Discord.Net.Core/Entities/Guilds/GuildProperties.cs index eccd852dd..0ffe8db35 100644 --- a/src/Discord.Net.Core/Entities/Guilds/GuildProperties.cs +++ b/src/Discord.Net.Core/Entities/Guilds/GuildProperties.cs @@ -1,7 +1,7 @@ namespace Discord { /// - /// Properties that are used to modify an with the specified changes. + /// Provides properties that are used to modify an with the specified changes. /// /// public class GuildProperties diff --git a/src/Discord.Net.Core/Entities/Guilds/IGuild.cs b/src/Discord.Net.Core/Entities/Guilds/IGuild.cs index 2f7aeca52..06348aa7f 100644 --- a/src/Discord.Net.Core/Entities/Guilds/IGuild.cs +++ b/src/Discord.Net.Core/Entities/Guilds/IGuild.cs @@ -22,7 +22,7 @@ namespace Discord /// automatically moved to the AFK voice channel. /// /// - /// An representing the amount of time in seconds for a user to be marked as inactive + /// An representing the amount of time in seconds for a user to be marked as inactive /// and moved into the AFK voice channel. /// int AFKTimeout { get; } @@ -98,63 +98,88 @@ namespace Discord /// Gets the ID of the AFK voice channel for this guild. /// /// - /// An representing the snowflake identifier of the AFK voice channel; null if + /// A representing the snowflake identifier of the AFK voice channel; null if /// none is set. /// ulong? AFKChannelId { get; } /// - /// Gets the ID of the the default channel for this guild. + /// Gets the ID of the default channel for this guild. /// + /// + /// This property retrieves the snowflake identifier of the first viewable text channel for this guild. + /// + /// This channel does not guarantee the user can send message to it, as it only looks for the first viewable + /// text channel. + /// + /// + /// + /// A representing the snowflake identifier of the default text channel; 0 if + /// none can be found. + /// ulong DefaultChannelId { get; } /// - /// Gets the ID of the embed channel set in the widget settings of this guild, or null if none is set. + /// Gets the ID of the widget embed channel of this guild. /// + /// + /// A representing the snowflake identifier of the embedded channel found within the + /// widget settings of this guild; null if none is set. + /// ulong? EmbedChannelId { get; } /// - /// Gets the ID of the channel where randomized welcome messages are sent, or null if none is set. + /// Gets the ID of the channel where randomized welcome messages are sent. /// + /// + /// A representing the snowflake identifier of the system channel where randomized + /// welcome messages are sent; null if none is set. + /// ulong? SystemChannelId { get; } /// - /// Gets the ID of the user that created this guild. + /// Gets the ID of the user that owns this guild. /// + /// + /// A representing the snowflake identifier of the user that owns this guild. + /// ulong OwnerId { get; } /// /// Gets the ID of the region hosting this guild's voice channels. /// + /// + /// A string containing the identifier for the voice region that this guild uses (e.g. eu-central). + /// string VoiceRegionId { get; } /// - /// Gets the currently associated with this guild. + /// Gets the currently associated with this guild. /// /// - /// currently associated with this guild. + /// An currently associated with this guild. /// IAudioClient AudioClient { get; } /// /// Gets the built-in role containing all users in this guild. /// /// - /// Built-in role that represents an @everyone role in this guild. + /// A role object that represents an @everyone role in this guild. /// IRole EveryoneRole { get; } /// /// Gets a collection of all custom emotes for this guild. /// /// - /// A collection of all custom emotes for this guild. + /// A read-only collection of all custom emotes for this guild. /// IReadOnlyCollection Emotes { get; } /// /// Gets a collection of all extra features added to this guild. /// /// - /// A collection of enabled features in this guild. + /// A read-only collection of enabled features in this guild. /// IReadOnlyCollection Features { get; } /// /// Gets a collection of all roles in this guild. /// /// - /// A collection of roles found within this guild. + /// A read-only collection of roles found within this guild. /// IReadOnlyCollection Roles { get; } @@ -164,7 +189,7 @@ namespace Discord /// The delegate containing the properties to modify the guild with. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task that represents the asynchronous modification operation. /// Task ModifyAsync(Action func, RequestOptions options = null); /// @@ -173,7 +198,7 @@ namespace Discord /// The delegate containing the properties to modify the guild widget with. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task that represents the asynchronous modification operation. /// Task ModifyEmbedAsync(Action func, RequestOptions options = null); /// @@ -182,7 +207,7 @@ namespace Discord /// The properties used to modify the channel positions with. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task that represents the asynchronous reorder operation. /// Task ReorderChannelsAsync(IEnumerable args, RequestOptions options = null); /// @@ -191,28 +216,32 @@ namespace Discord /// The properties used to modify the role positions with. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task that represents the asynchronous reorder operation. /// Task ReorderRolesAsync(IEnumerable args, RequestOptions options = null); /// /// Leaves this guild. /// /// - /// This method will make the currently logged-in user leave the guild. If the user is the owner, use - /// instead. + /// This method will make the currently logged-in user leave the guild. + /// + /// If the user is the owner of this guild, use instead. + /// /// /// The options to be used when sending the request. /// - /// An awaitable . + /// A task that represents the asynchronous leave operation. /// Task LeaveAsync(RequestOptions options = null); /// - /// Gets a collection of all users banned on this guild. + /// Gets a collection of all users banned in this guild. /// /// The options to be used when sending the request. /// - /// An awaitable containing a collection of banned users with reasons. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection of + /// ban objects that this guild currently possesses, with each object containing the user banned and reason + /// behind the ban. /// Task> GetBansAsync(RequestOptions options = null); /// @@ -221,8 +250,8 @@ namespace Discord /// The banned user. /// The options to be used when sending the request. /// - /// An awaitable containing the ban object, which contains the user information and the - /// reason for the ban; null if the ban entry cannot be found. + /// A task that represents the asynchronous get operation. The task result contains a ban object, which + /// contains the user information and the reason for the ban; null if the ban entry cannot be found. /// Task GetBanAsync(IUser user, RequestOptions options = null); /// @@ -231,216 +260,197 @@ namespace Discord /// The snowflake identifier for the banned user. /// The options to be used when sending the request. /// - /// An awaitable containing the ban object, which contains the user information and the - /// reason for the ban; null if the ban entry cannot be found. + /// A task that represents the asynchronous get operation. The task result contains a ban object, which + /// contains the user information and the reason for the ban; null if the ban entry cannot be found. /// Task GetBanAsync(ulong userId, RequestOptions options = null); /// /// Bans the user from this guild and optionally prunes their recent messages. /// /// The user to ban. - /// - /// The number of days to remove messages from this for - must be between [0, 7]. - /// + /// The number of days to remove messages from this user for, and this number must be between [0, 7]. /// The reason of the ban to be written in the audit log. /// The options to be used when sending the request. - /// is not between 0 to 7. + /// is not between 0 to 7. /// - /// An awaitable . + /// A task that represents the asynchronous add operation for the ban. /// Task AddBanAsync(IUser user, int pruneDays = 0, string reason = null, RequestOptions options = null); /// /// Bans the user from this guild and optionally prunes their recent messages. /// /// The snowflake ID of the user to ban. - /// - /// The number of days to remove messages from this user for - must be between [0, 7]. - /// + /// The number of days to remove messages from this user for, and this number must be between [0, 7]. /// The reason of the ban to be written in the audit log. /// The options to be used when sending the request. - /// is not between 0 to 7. + /// is not between 0 to 7. /// - /// An awaitable . + /// A task that represents the asynchronous add operation for the ban. /// Task AddBanAsync(ulong userId, int pruneDays = 0, string reason = null, RequestOptions options = null); /// - /// Unbans the provided user if they are currently banned. + /// Unbans the user if they are currently banned. /// /// The user to be unbanned. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task that represents the asynchronous removal operation for the ban. /// Task RemoveBanAsync(IUser user, RequestOptions options = null); /// - /// Unbans the provided user ID if it is currently banned. + /// Unbans the user if they are currently banned. /// - /// The snowflake ID of the user to be unbanned. + /// The snowflake identifier of the user to be unbanned. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task that represents the asynchronous removal operation for the ban. /// Task RemoveBanAsync(ulong userId, RequestOptions options = null); /// /// Gets a collection of all channels in this guild. /// - /// - /// 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. /// - /// An awaitable containing a collection of generic channels found within this guild. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection of + /// generic channels found within this guild. /// Task> GetChannelsAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// - /// Gets the channel in this guild with the provided ID. + /// Gets a channel in this guild. /// - /// The channel ID. - /// - /// The that determines whether the object should be fetched from cache. - /// + /// The snowflake identifier for the channel. + /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing the generic channel with the specified ID, or - /// null if none is found. + /// A task that represents the asynchronous get operation. The task result contains the generic channel + /// associated with the specified ; null if none is found. /// Task GetChannelAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// /// Gets a collection of all text channels in this guild. /// - /// - /// 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. /// - /// An awaitable containing a collection of text channels found within this guild. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection of + /// message channels found within this guild. /// Task> GetTextChannelsAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// - /// Gets a text channel in this guild with the provided ID, or null if not found. + /// Gets a text channel in this guild. /// - /// The text channel ID. - /// - /// The that determines whether the object should be fetched from cache. - /// + /// The snowflake identifier for the text channel. + /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing the text channel with the specified ID, or - /// null if none is found. + /// A task that represents the asynchronous get operation. The task result contains the text channel + /// associated with the specified ; null if none is found. /// Task GetTextChannelAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// /// Gets a collection of all voice channels in this guild. /// - /// - /// 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. /// - /// An awaitable containing a collection of voice channels found within this guild. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection of + /// voice channels found within this guild. /// Task> GetVoiceChannelsAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// /// Gets a collection of all category channels in this guild. /// - /// - /// 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. /// - /// An awaitable containing a collection of category channels found within this guild. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection of + /// category channels found within this guild. /// Task> GetCategoriesAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// - /// Gets the voice channel in this guild with the provided ID. + /// Gets a voice channel in this guild. /// - /// The text channel ID. - /// - /// The that determines whether the object should be fetched from cache. - /// + /// The snowflake identifier for the voice channel. + /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing the voice channel with the specified ID, or - /// null if none is found. + /// A task that represents the asynchronous get operation. The task result contains the voice channel associated + /// with the specified ; null if none is found. /// Task GetVoiceChannelAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// /// Gets the AFK voice channel in this guild. /// - /// - /// 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. /// - /// An awaitable containing the AFK voice channel set within this guild, or - /// null if none is set. + /// A task that represents the asynchronous get operation. The task result contains the voice channel that the + /// AFK users will be moved to after they have idled for too long; null if none is set. /// Task GetAFKChannelAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// - /// Gets the default system text channel in this guild with the provided ID. + /// Gets the system channel where randomized welcome messages are sent in this guild. /// - /// - /// 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. /// - /// An awaitable containing the system channel within this guild, or - /// null if none is set. + /// A task that represents the asynchronous get operation. The task result contains the text channel where + /// randomized welcome messages will be sent to; null if none is set. /// Task GetSystemChannelAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// - /// Gets the top viewable text channel in this guild with the provided ID. + /// Gets the first viewable text channel in this guild. /// - /// - /// 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. /// - /// An awaitable containing the first viewable text channel in this guild, or - /// null if none is found. + /// A task that represents the asynchronous get operation. The task result contains the first viewable text + /// channel in this guild; null if none is found. /// Task GetDefaultChannelAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// /// Gets the embed channel (i.e. the channel set in the guild's widget settings) in this guild. /// - /// - /// 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. /// - /// An awaitable containing the embed channel set within the server's widget settings, or - /// null if none is set. + /// A task that represents the asynchronous get operation. The task result contains the embed channel set + /// within the server's widget settings; null if none is set. /// Task GetEmbedChannelAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// - /// Creates a new text channel. + /// Creates a new text channel in this guild. /// /// The new name for the text channel. /// The delegate containing the properties to be applied to the channel upon its creation. /// The options to be used when sending the request. /// - /// An awaitable containing the newly created text channel. + /// A task that represents the asynchronous creation operation. The task result contains the newly created + /// text channel. /// Task CreateTextChannelAsync(string name, Action func = null, RequestOptions options = null); /// - /// Creates a new voice channel. + /// Creates a new voice channel in this guild. /// /// The new name for the voice channel. /// The delegate containing the properties to be applied to the channel upon its creation. /// The options to be used when sending the request. /// - /// An awaitable containing the newly created voice channel. + /// A task that represents the asynchronous creation operation. The task result contains the newly created + /// voice channel. /// Task CreateVoiceChannelAsync(string name, Action func = null, RequestOptions options = null); /// - /// Creates a new channel category. + /// Creates a new channel category in this guild. /// /// The new name for the category. /// The options to be used when sending the request. /// - /// An awaitable containing the newly created category channel. + /// A task that represents the asynchronous creation operation. The task result contains the newly created + /// category channel. /// Task CreateCategoryAsync(string name, RequestOptions options = null); @@ -448,11 +458,12 @@ namespace Discord Task CreateIntegrationAsync(ulong id, string type, RequestOptions options = null); /// - /// Gets a collection of all invites to this guild. + /// Gets a collection of all invites in this guild. /// /// The options to be used when sending the request. /// - /// An awaitable containing a collection of invites found within this guild. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection of + /// invite metadata, each representing information for an invite found within this guild. /// Task> GetInvitesAsync(RequestOptions options = null); /// @@ -460,17 +471,17 @@ namespace Discord /// /// The options to be used when sending the request. /// - /// An awaitable containing the partial metadata of the vanity invite found within - /// this guild. + /// A task that represents the asynchronous get operation. The task result contains the partial metadata of + /// the vanity invite found within this guild; null if none is found. /// Task GetVanityInviteAsync(RequestOptions options = null); /// /// Gets a role in this guild. /// - /// The role ID. + /// The snowflake identifier for the role. /// - /// A role that matches the provided snowflake identifier; null if none is found. + /// A role that is associated with the specified ; null if none is found. /// IRole GetRole(ulong id); /// @@ -482,7 +493,8 @@ namespace Discord /// Whether the role is separated from others on the sidebar. /// The options to be used when sending the request. /// - /// An awaitable containing the newly crated role. + /// A task that represents the asynchronous creation operation. The task result contains the newly created + /// role. /// Task CreateRoleAsync(string name, GuildPermissions? permissions = null, Color? color = null, bool isHoisted = false, RequestOptions options = null); @@ -492,27 +504,33 @@ namespace Discord /// /// This method retrieves all users found within this guild. /// - /// This may return an incomplete list on the WebSocket implementation. + /// This may return an incomplete collection in the WebSocket implementation due to how Discord does not + /// send a complete user list for large guilds. /// /// - /// - /// 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. /// - /// An awaitable containing a collection of users found within this guild. + /// A task that represents the asynchronous get operation. The task result contains a collection of guild + /// users found within this guild. /// Task> GetUsersAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// - /// Gets a user found in this guild. + /// Gets a user from this guild. /// - /// The user ID to search for. - /// The that determines whether the object should be fetched from - /// cache. + /// + /// This method retrieves a user found within this guild. + /// + /// This may return null in the WebSocket implementation due to incomplete user collection in + /// large guilds. + /// + /// + /// The snowflake identifier of the user. + /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing the guild user with the specified ID; null if none is - /// found. + /// A task that represents the asynchronous get operation. The task result contains the guild user + /// associated with the specified ; null if none is found. /// Task GetUserAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// @@ -521,7 +539,8 @@ namespace Discord /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing the currently logged-in user within this guild. + /// A task that represents the asynchronous get operation. The task result contains the currently logged-in + /// user within this guild. /// Task GetCurrentUserAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// @@ -530,29 +549,34 @@ namespace Discord /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing the owner of this guild. + /// A task that represents the asynchronous get operation. The task result contains the owner of this guild. /// Task GetOwnerAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// /// Downloads all users for this guild if the current list is incomplete. /// /// - /// An awaitable . + /// A task that represents the asynchronous download operation. /// Task DownloadUsersAsync(); /// /// Prunes inactive users. /// /// - /// This method removes all users that have not logged on in the provided number of days or, if - /// is true, returns the number of users that would be removed. + /// + /// This method removes all users that have not logged on in the provided number of . + /// + /// + /// If is true, this method will only return the number of users that + /// would be removed without kicking the users. + /// /// /// The number of days required for the users to be kicked. /// Whether this prune action is a simulation. /// The options to be used when sending the request. /// - /// An awaitable containing the number of users to be or has been removed from this - /// guild. + /// A task that represents the asynchronous prune operation. The task result contains the number of users to + /// be or has been removed from this guild. /// Task PruneUsersAsync(int days = 30, bool simulate = false, RequestOptions options = null); @@ -560,24 +584,23 @@ namespace Discord /// Gets the specified number of audit log entries for this guild. /// /// The number of audit log entries to fetch. - /// - /// 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. /// - /// An awaitable containing a collection of requested audit log entries. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection + /// of the requested audit log entries. /// - Task> GetAuditLogAsync(int limit = DiscordConfig.MaxAuditLogEntriesPerBatch, + Task> GetAuditLogsAsync(int limit = DiscordConfig.MaxAuditLogEntriesPerBatch, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// /// Gets a webhook found within this guild. /// - /// The webhook ID. + /// The identifier for the webhook. /// The options to be used when sending the request. /// - /// An awaitable containing the webhook with the specified ID; null if none is - /// found. + /// A task that represents the asynchronous get operation. The task result contains the webhook with the + /// specified ; null if none is found. /// Task GetWebhookAsync(ulong id, RequestOptions options = null); /// @@ -585,18 +608,19 @@ namespace Discord /// /// The options to be used when sending the request. /// - /// An awaitable containing a collection of webhooks found within the guild. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection + /// of webhooks found within the guild. /// Task> GetWebhooksAsync(RequestOptions options = null); /// /// Gets a specific emote from this guild. /// - /// The guild emote ID. + /// The snowflake identifier for the guild emote. /// The options to be used when sending the request. /// - /// An awaitable containing the emote found with the specified ID; null if none is - /// found. + /// A task that represents the asynchronous get operation. The task result contains the emote found with the + /// specified ; null if none is found. /// Task GetEmoteAsync(ulong id, RequestOptions options = null); /// @@ -607,7 +631,7 @@ namespace Discord /// The roles to limit the emote usage to. /// The options to be used when sending the request. /// - /// An awaitable containing the created emote. + /// A task that represents the asynchronous creation operation. The task result contains the created emote. /// Task CreateEmoteAsync(string name, Image image, Optional> roles = default(Optional>), RequestOptions options = null); @@ -618,7 +642,8 @@ namespace Discord /// The delegate containing the properties to modify the emote with. /// The options to be used when sending the request. /// - /// An awaitable containing the newly modified emote. + /// A task that represents the asynchronous modification operation. The task result contains the modified + /// emote. /// Task ModifyEmoteAsync(GuildEmote emote, Action func, RequestOptions options = null); /// @@ -627,7 +652,7 @@ namespace Discord /// The emote to delete. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task that represents the asynchronous removal operation. /// Task DeleteEmoteAsync(GuildEmote emote, 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/ISnowflakeEntity.cs b/src/Discord.Net.Core/Entities/ISnowflakeEntity.cs index f5dd2ab07..9c7b3721f 100644 --- a/src/Discord.Net.Core/Entities/ISnowflakeEntity.cs +++ b/src/Discord.Net.Core/Entities/ISnowflakeEntity.cs @@ -5,7 +5,12 @@ namespace Discord /// Represents a Discord snowflake entity. public interface ISnowflakeEntity : IEntity { - /// Gets when the snowflake is created. + /// + /// Gets when the snowflake is created. + /// + /// + /// A representing when the entity was first created. + /// DateTimeOffset CreatedAt { 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/Permissions/GuildPermissions.cs b/src/Discord.Net.Core/Entities/Permissions/GuildPermissions.cs index 9ad7d34b4..bac14a5c8 100644 --- a/src/Discord.Net.Core/Entities/Permissions/GuildPermissions.cs +++ b/src/Discord.Net.Core/Entities/Permissions/GuildPermissions.cs @@ -148,7 +148,7 @@ namespace Discord RawValue = value; } - /// Creates a new with the provided permissions. + /// Creates a new structure with the provided permissions. public GuildPermissions( bool createInstantInvite = false, bool kickMembers = false, diff --git a/src/Discord.Net.Core/Entities/Roles/Color.cs b/src/Discord.Net.Core/Entities/Roles/Color.cs index b3de6d5ff..a8917ec07 100644 --- a/src/Discord.Net.Core/Entities/Roles/Color.cs +++ b/src/Discord.Net.Core/Entities/Roles/Color.cs @@ -18,61 +18,60 @@ namespace Discord /// A color class with the hex value of 1ABC9C. public static readonly Color Teal = new Color(0x1ABC9C); /// Gets the dark teal color value. - /// A color class with the hex value of 11806A. public static readonly Color DarkTeal = new Color(0x11806A); /// Gets the green color value. - /// A color class with the hex value of 2ECC71. + /// A color class with the hex value of 11806A. public static readonly Color Green = new Color(0x2ECC71); /// Gets the dark green color value. - /// A color class with the hex value of 1F8B4C. + /// A color class with the hex value of 2ECC71. public static readonly Color DarkGreen = new Color(0x1F8B4C); /// Gets the blue color value. - /// A color class with the hex value of 3498DB. + /// A color class with the hex value of 1F8B4C. public static readonly Color Blue = new Color(0x3498DB); /// Gets the dark blue color value. - /// A color class with the hex value of 206694. + /// A color class with the hex value of 3498DB. public static readonly Color DarkBlue = new Color(0x206694); /// Gets the purple color value. - /// A color class with the hex value of 9B59B6. + /// A color class with the hex value of 206694. public static readonly Color Purple = new Color(0x9B59B6); /// Gets the dark purple color value. - /// A color class with the hex value of 71368A. + /// A color class with the hex value of 9B59B6. public static readonly Color DarkPurple = new Color(0x71368A); /// Gets the magenta color value. - /// A color class with the hex value of E91E63. + /// A color class with the hex value of 71368A. public static readonly Color Magenta = new Color(0xE91E63); /// Gets the dark magenta color value. - /// A color class with the hex value of AD1457. + /// A color class with the hex value of E91E63. public static readonly Color DarkMagenta = new Color(0xAD1457); /// Gets the gold color value. - /// A color class with the hex value of F1C40F. + /// A color class with the hex value of AD1457. public static readonly Color Gold = new Color(0xF1C40F); /// Gets the light orange color value. - /// A color class with the hex value of C27C0E. + /// A color class with the hex value of F1C40F. public static readonly Color LightOrange = new Color(0xC27C0E); /// Gets the orange color value. - /// A color class with the hex value of E67E22. + /// A color class with the hex value of C27C0E. public static readonly Color Orange = new Color(0xE67E22); /// Gets the dark orange color value. - /// A color class with the hex value of A84300. + /// A color class with the hex value of E67E22. public static readonly Color DarkOrange = new Color(0xA84300); /// Gets the red color value. - /// A color class with the hex value of E74C3C. + /// A color class with the hex value of A84300. public static readonly Color Red = new Color(0xE74C3C); /// Gets the dark red color value. - /// A color class with the hex value of 992D22. - public static readonly Color DarkRed = new Color(0x992D22); + /// A color class with the hex value of E74C3C. + public static readonly Color DarkRed = new Color(0x992D22); /// Gets the light grey color value. - /// A color class with the hex value of 979C9F. + /// A color class with the hex value of 992D22. public static readonly Color LightGrey = new Color(0x979C9F); /// Gets the lighter grey color value. - /// A color class with the hex value of 95A5A6. + /// A color class with the hex value of 979C9F. public static readonly Color LighterGrey = new Color(0x95A5A6); /// Gets the dark grey color value. - /// A color class with the hex value of 607D8B. + /// A color class with the hex value of 95A5A6. public static readonly Color DarkGrey = new Color(0x607D8B); /// Gets the darker grey color value. - /// A color class with the hex value of 546E7A. + /// A color class with the hex value of 607D8B. public static readonly Color DarkerGrey = new Color(0x546E7A); /// Gets the encoded value for this color. 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/Roles/ReorderRoleProperties.cs b/src/Discord.Net.Core/Entities/Roles/ReorderRoleProperties.cs index 6c6c1ebc9..0074c0a3b 100644 --- a/src/Discord.Net.Core/Entities/Roles/ReorderRoleProperties.cs +++ b/src/Discord.Net.Core/Entities/Roles/ReorderRoleProperties.cs @@ -16,7 +16,7 @@ namespace Discord /// Gets the new zero-based position of the role. /// /// - /// A representing the new zero-based position of the role. + /// An representing the new zero-based position of the role. /// public int Position { get; } diff --git a/src/Discord.Net.Core/Entities/Users/IGuildUser.cs b/src/Discord.Net.Core/Entities/Users/IGuildUser.cs index 4d54a49c4..633056733 100644 --- a/src/Discord.Net.Core/Entities/Users/IGuildUser.cs +++ b/src/Discord.Net.Core/Entities/Users/IGuildUser.cs @@ -10,36 +10,60 @@ namespace Discord public interface IGuildUser : IUser, IVoiceState { /// - /// Gets when this user joined this guild. + /// Gets when this user joined the guild. /// + /// + /// A representing the time of which the user has joined the guild; + /// null when it cannot be obtained. + /// DateTimeOffset? JoinedAt { get; } /// /// Gets the nickname for this user. /// + /// + /// A string representing the nickname of the user; null if none is set. + /// string Nickname { get; } /// /// Gets the guild-level permissions for this user. /// + /// + /// A structure for this user, representing what + /// permissions this user has in the guild. + /// GuildPermissions GuildPermissions { get; } /// /// Gets the guild for this user. /// + /// + /// A guild object that this user belongs to. + /// IGuild Guild { get; } /// /// Gets the ID of the guild for this user. /// + /// + /// An representing the snowflake identifier of the guild that this user belongs to. + /// ulong GuildId { get; } /// - /// Returns a collection of the ids of the roles this user is a member of in this guild, including the - /// guild's @everyone role. + /// Gets a collection of IDs for the roles that this user currently possesses in the guild. /// + /// + /// A read-only collection of , each representing a snowflake identifier for a role that + /// this user posesses. + /// IReadOnlyCollection RoleIds { get; } /// /// Gets the level permissions granted to this user to a given channel. /// /// The channel to get the permission from. + /// + /// A structure representing the permissions that a user has in the + /// specified channel. + /// ChannelPermissions GetPermissions(IGuildChannel channel); /// @@ -47,37 +71,56 @@ namespace Discord /// /// The reason for the kick which will be recorded in the audit log. /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous kick operation. + /// Task KickAsync(string reason = null, RequestOptions options = null); /// /// Modifies this user's properties in this guild. /// - /// The properties to modify the user with. + /// The delegate containing the properties to modify the user with. /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous modification operation. + /// + /// Task ModifyAsync(Action func, RequestOptions options = null); /// - /// Adds a to this user in this guild. + /// Adds the specified to this user in this guild. /// /// The role to be added to the user. /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous role addition operation. + /// Task AddRoleAsync(IRole role, RequestOptions options = null); /// - /// Adds to this user in this guild. + /// Adds the specified to this user in this guild. /// /// The roles to be added to the user. /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous role addition operation. + /// Task AddRolesAsync(IEnumerable roles, RequestOptions options = null); /// - /// Removes a from this user in this guild. + /// Removes the specified from this user in this guild. /// /// The role to be removed from the user. /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous role removal operation. + /// Task RemoveRoleAsync(IRole role, RequestOptions options = null); /// - /// Removes from this user in this guild. + /// Removes the specified from this user in this guild. /// /// The roles to be removed from the user. /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous role removal operation. + /// Task RemoveRolesAsync(IEnumerable roles, RequestOptions options = null); } } 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/Entities/Users/ISelfUser.cs b/src/Discord.Net.Core/Entities/Users/ISelfUser.cs index 1ead0cbba..c1d7874eb 100644 --- a/src/Discord.Net.Core/Entities/Users/ISelfUser.cs +++ b/src/Discord.Net.Core/Entities/Users/ISelfUser.cs @@ -13,12 +13,18 @@ namespace Discord /// string Email { get; } /// - /// Returns true if this user's email has been verified. + /// Indicates whether or not this user has their email verified. /// + /// + /// true if this user's email has been verified; false if not. + /// bool IsVerified { get; } /// - /// Returns true if this user has enabled MFA on their account. + /// Indicates whether or not this user has MFA enabled on their account. /// + /// + /// true if this user has enabled multi-factor authentication on their account; false if not. + /// bool IsMfaEnabled { get; } /// 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/Net/RateLimitedException.cs b/src/Discord.Net.Core/Net/RateLimitedException.cs index 6e084886e..c19487fad 100644 --- a/src/Discord.Net.Core/Net/RateLimitedException.cs +++ b/src/Discord.Net.Core/Net/RateLimitedException.cs @@ -3,7 +3,7 @@ using System; namespace Discord.Net { /// - /// Describes an exception that indicates the user is being rate limited by Discord. + /// The exception that is thrown when the user is being rate limited by Discord. /// public class RateLimitedException : TimeoutException { 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.Rest/Entities/Channels/RestTextChannel.cs b/src/Discord.Net.Rest/Entities/Channels/RestTextChannel.cs index 2a9000f16..f1a282dc9 100644 --- a/src/Discord.Net.Rest/Entities/Channels/RestTextChannel.cs +++ b/src/Discord.Net.Rest/Entities/Channels/RestTextChannel.cs @@ -16,14 +16,13 @@ namespace Discord.Rest { /// public string Topic { get; private set; } + /// public ulong? CategoryId { get; private set; } /// public string Mention => MentionUtils.MentionChannel(Id); - - private bool _nsfw; /// - public bool IsNsfw => _nsfw; + public bool IsNsfw { get; private set; } internal RestTextChannel(BaseDiscordClient discord, IGuild guild, ulong id) : base(discord, guild, id) @@ -40,7 +39,7 @@ namespace Discord.Rest base.Update(model); CategoryId = model.CategoryId; Topic = model.Topic.Value; - _nsfw = model.Nsfw.GetValueOrDefault(); + IsNsfw = model.Nsfw.GetValueOrDefault(); } /// @@ -239,6 +238,7 @@ namespace Discord.Rest } // INestedChannel + /// async Task INestedChannel.GetCategoryAsync(CacheMode mode, RequestOptions options) { if (CategoryId.HasValue && mode == CacheMode.AllowDownload) diff --git a/src/Discord.Net.Rest/Entities/Channels/RestVoiceChannel.cs b/src/Discord.Net.Rest/Entities/Channels/RestVoiceChannel.cs index f54013950..a2b086258 100644 --- a/src/Discord.Net.Rest/Entities/Channels/RestVoiceChannel.cs +++ b/src/Discord.Net.Rest/Entities/Channels/RestVoiceChannel.cs @@ -18,6 +18,7 @@ namespace Discord.Rest public int Bitrate { get; private set; } /// public int? UserLimit { get; private set; } + /// public ulong? CategoryId { get; private set; } internal RestVoiceChannel(BaseDiscordClient discord, IGuild guild, ulong id) diff --git a/src/Discord.Net.Rest/Entities/Guilds/RestGuild.cs b/src/Discord.Net.Rest/Entities/Guilds/RestGuild.cs index 606d24450..0d1b20680 100644 --- a/src/Discord.Net.Rest/Entities/Guilds/RestGuild.cs +++ b/src/Discord.Net.Rest/Entities/Guilds/RestGuild.cs @@ -553,7 +553,7 @@ namespace Discord.Rest Task IGuild.DownloadUsersAsync() => throw new NotSupportedException(); - async Task> IGuild.GetAuditLogAsync(int limit, CacheMode cacheMode, RequestOptions options) + async Task> IGuild.GetAuditLogsAsync(int limit, CacheMode cacheMode, RequestOptions options) { if (cacheMode == CacheMode.AllowDownload) return (await GetAuditLogsAsync(limit, options).FlattenAsync().ConfigureAwait(false)).ToImmutableArray(); diff --git a/src/Discord.Net.Rest/Entities/Messages/RestSystemMessage.cs b/src/Discord.Net.Rest/Entities/Messages/RestSystemMessage.cs index b9dda08ae..4d61f8638 100644 --- a/src/Discord.Net.Rest/Entities/Messages/RestSystemMessage.cs +++ b/src/Discord.Net.Rest/Entities/Messages/RestSystemMessage.cs @@ -1,4 +1,4 @@ -using System.Diagnostics; +using System.Diagnostics; using Model = Discord.API.Message; namespace Discord.Rest @@ -6,6 +6,7 @@ namespace Discord.Rest [DebuggerDisplay(@"{DebuggerDisplay,nq}")] public class RestSystemMessage : RestMessage, ISystemMessage { + /// public MessageType Type { get; private set; } internal RestSystemMessage(BaseDiscordClient discord, ulong id, IMessageChannel channel, IUser author) diff --git a/src/Discord.Net.WebSocket/Entities/Channels/SocketDMChannel.cs b/src/Discord.Net.WebSocket/Entities/Channels/SocketDMChannel.cs index c0a042669..ee33b3b93 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 e18bd9be8..f77dedb3e 100644 --- a/src/Discord.Net.WebSocket/Entities/Channels/SocketTextChannel.cs +++ b/src/Discord.Net.WebSocket/Entities/Channels/SocketTextChannel.cs @@ -23,10 +23,10 @@ namespace Discord.WebSocket /// public ulong? CategoryId { get; private set; } /// - /// Gets the Category this channel belongs to. + /// Gets the parent (category) of this channel in the guild's channel list. /// /// - /// An that this channel belongs to; otherwise null. + /// An representing the parent of this channel; null if none is set. /// public ICategoryChannel Category => CategoryId.HasValue ? Guild.GetChannel(CategoryId.Value) as ICategoryChannel : null; @@ -73,14 +73,14 @@ namespace Discord.WebSocket /// public SocketMessage GetCachedMessage(ulong id) => _messages?.Get(id); - /// - /// Gets the message associated with the passed . + /// Gets a message from this message channel. /// - /// The snowflake identifier of the message you want to retrieve. + /// The ID of the message. /// The options to be used when sending the request. /// - /// An awaitable containing an . + /// 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) { @@ -89,11 +89,10 @@ 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 number of messages you want to get. + /// 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 @@ -101,8 +100,30 @@ namespace Discord.WebSocket /// 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); /// @@ -119,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); @@ -135,6 +159,7 @@ 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); @@ -177,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); @@ -187,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); @@ -196,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); @@ -256,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..c095f0e03 100644 --- a/src/Discord.Net.WebSocket/Entities/Guilds/SocketGuild.cs +++ b/src/Discord.Net.WebSocket/Entities/Guilds/SocketGuild.cs @@ -54,8 +54,18 @@ namespace Discord.WebSocket /// Gets the number of members. /// /// - /// This property retrieves the number of members returned by Discord and is the most accurate. You may see - /// discrepancy between the collection and this property. + /// This property retrieves the number of members returned by Discord. + /// + /// + /// Due to how this property is returned by Discord instead of relying on the WebSocket cache, the + /// number here is the most accurate in terms of counting the number of users within this guild. + /// + /// + /// Use this instead of enumerating the count of the + /// collection, as you may see discrepancy + /// between that and this property. + /// + /// /// public int MemberCount { get; internal set; } /// Gets the number of members downloaded to the local guild cache. @@ -95,12 +105,18 @@ namespace Discord.WebSocket /// public IAudioClient AudioClient => _audioClient; /// - /// Gets the first viewable text channel. + /// Gets the default channel in this guild. /// /// - /// This method gets the first viewable text channel for the logged-in user. This property does not - /// guarantee the user can send message to it. + /// This property retrieves the first viewable text channel for this guild. + /// + /// This channel does not guarantee the user can send message to it, as it only looks for the first viewable + /// text channel. + /// /// + /// + /// A representing the first viewable channel that the user has access to. + /// public SocketTextChannel DefaultChannel => TextChannels .Where(c => CurrentUser.GetPermissions(c).ViewChannel) .OrderBy(c => c.Position) @@ -109,7 +125,8 @@ namespace Discord.WebSocket /// Gets the AFK voice channel in this guild. /// /// - /// A voice channel set within this guild that AFK users get moved to; otherwise null if none is set. + /// A that the AFK users will be moved to after they have idled for too + /// long; null if none is set. /// public SocketVoiceChannel AFKChannel { @@ -120,10 +137,10 @@ namespace Discord.WebSocket } } /// - /// Gets the embed channel set in the widget settings of this guild. + /// Gets the embed channel (i.e. the channel set in the guild's widget settings) in this guild. /// /// - /// A channel set in the widget settings of this guild; otherwise null if none is set. + /// A channel set within the server's widget settings; null if none is set. /// public SocketGuildChannel EmbedChannel { @@ -134,11 +151,10 @@ namespace Discord.WebSocket } } /// - /// Gets the channel where randomized welcome messages are sent. + /// Gets the system channel where randomized welcome messages are sent in this guild. /// /// - /// A channel where randomized welcome messages are sent in this guild; otherwise null if none is - /// set. + /// A text channel where randomized welcome messages will be sent to; null if none is set. /// public SocketTextChannel SystemChannel { @@ -149,21 +165,27 @@ namespace Discord.WebSocket } } /// - /// Gets a collection of text channels present in this guild. + /// Gets a collection of all text channels in this guild. /// /// - /// A collection of text channels in this guild. + /// A read-only collection of message channels found within this guild. /// public IReadOnlyCollection TextChannels => Channels.Select(x => x as SocketTextChannel).Where(x => x != null).ToImmutableArray(); /// - /// Gets a collection of voice channels present in this guild. + /// Gets a collection of all voice channels in this guild. /// + /// + /// A read-only collection of voice channels found within this guild. + /// public IReadOnlyCollection VoiceChannels => Channels.Select(x => x as SocketVoiceChannel).Where(x => x != null).ToImmutableArray(); /// - /// Gets a collection of category channels present in this guild. + /// Gets a collection of all category channels in this guild. /// + /// + /// A read-only collection of category channels found within this guild. + /// public IReadOnlyCollection CategoryChannels => Channels.Select(x => x as SocketCategoryChannel).Where(x => x != null).ToImmutableArray(); /// @@ -171,14 +193,17 @@ namespace Discord.WebSocket /// public SocketGuildUser CurrentUser => _members.TryGetValue(Discord.CurrentUser.Id, out SocketGuildUser member) ? member : null; /// - /// Gets the @everyone role in this guild. + /// Gets the built-in role containing all users in this guild. /// + /// + /// A role object that represents an @everyone role in this guild. + /// public SocketRole EveryoneRole => GetRole(Id); /// - /// Gets a collection of channels present in this guild. + /// Gets a collection of all channels in this guild. /// /// - /// Collection of channels. + /// A read-only collection of generic channels found within this guild. /// public IReadOnlyCollection Channels { @@ -189,37 +214,37 @@ namespace Discord.WebSocket return channels.Select(x => state.GetChannel(x) as SocketGuildChannel).Where(x => x != null).ToReadOnlyCollection(channels); } } - /// - /// Gets a collection of emotes created in this guild. - /// - /// - /// Collection of emotes. - /// + /// public IReadOnlyCollection Emotes => _emotes; - /// - /// Gets a collection of features enabled in this guild. - /// - /// - /// Collection of features in string. - /// + /// public IReadOnlyCollection Features => _features; /// /// Gets a collection of users in this guild. /// /// - /// This property may not always return all the members for large guilds (i.e. guilds containing 100+ users). - /// You may need to enable to fetch the full user list - /// upon startup, or use to manually download the users. + /// This property retrieves all users found within this guild. + /// + /// + /// This property may not always return all the members for large guilds (i.e. guilds containing + /// 100+ users). If you are simply looking to get the number of users present in this guild, + /// consider using instead. + /// + /// + /// Otherwise, you may need to enable to fetch + /// the full user list upon startup, or use to manually download + /// the users. + /// + /// /// /// - /// Collection of users. + /// A collection of guild users found within this guild. /// public IReadOnlyCollection Users => _members.ToReadOnlyCollection(); /// - /// Gets a collection of roles in this guild. + /// Gets a collection of all roles in this guild. /// /// - /// Collection of roles. + /// A read-only collection of roles found within this guild. /// public IReadOnlyCollection Roles => _roles.ToReadOnlyCollection(); @@ -407,16 +432,36 @@ namespace Discord.WebSocket //Bans /// - /// Returns a collection of the banned users in this guild. + /// Gets a collection of all users banned in this guild. /// /// The options to be used when sending the request. /// - /// A collection of bans. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection of + /// ban objects that this guild currently possesses, with each object containing the user banned and reason + /// behind the ban. /// 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. + /// + /// A task that represents the asynchronous get operation. The task result contains a 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. + /// + /// A task that represents the asynchronous get operation. The task result contains a 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); @@ -436,11 +481,11 @@ namespace Discord.WebSocket //Channels /// - /// Returns a guild channel with the provided ID. + /// Gets a channel in this guild. /// - /// The channel ID. + /// The snowflake identifier for the channel. /// - /// The guild channel associated with the ID. + /// A generic channel associated with the specified ; null if none is found. /// public SocketGuildChannel GetChannel(ulong id) { @@ -450,56 +495,59 @@ namespace Discord.WebSocket return null; } /// - /// Returns a text channel with the provided ID. + /// Gets a text channel in this guild. /// - /// The channel ID. + /// The snowflake identifier for the text channel. /// - /// The text channel associated with the ID. + /// A text channel associated with the specified ; null if none is found. /// public SocketTextChannel GetTextChannel(ulong id) => GetChannel(id) as SocketTextChannel; /// - /// Returns a voice channel with the provided ID. + /// Gets a voice channel in this guild. /// - /// The channel ID. + /// The snowflake identifier for the voice channel. /// - /// The voice channel associated with the ID. + /// A voice channel associated with the specified ; null if none is found. /// public SocketVoiceChannel GetVoiceChannel(ulong id) => GetChannel(id) as SocketVoiceChannel; /// - /// Creates a text channel with the provided name. + /// Creates a new text channel in this guild. /// - /// The name of the new channel. - /// The options to be used when sending the request. + /// The new name for the text channel. /// The delegate containing the properties to be applied to the channel upon its creation. - /// is null. + /// The options to be used when sending the request. + /// is null. /// - /// The created text channel. + /// A task that represents the asynchronous creation operation. The task result contains the newly created + /// text channel. /// public Task CreateTextChannelAsync(string name, Action func = null, RequestOptions options = null) => GuildHelper.CreateTextChannelAsync(this, Discord, name, options, func); /// - /// Creates a voice channel with the provided name. + /// Creates a new voice channel in this guild. /// - /// The name of the new channel. + /// The new name for the voice channel. /// The delegate containing the properties to be applied to the channel upon its creation. /// The options to be used when sending the request. - /// is null. + /// is null. /// - /// The created voice channel. + /// A task that represents the asynchronous creation operation. The task result contains the newly created + /// voice channel. /// public Task CreateVoiceChannelAsync(string name, Action func = null, RequestOptions options = null) => GuildHelper.CreateVoiceChannelAsync(this, Discord, name, options, func); /// - /// Creates a category channel with the provided name. + /// Creates a new channel category in this guild. /// - /// The name of the new channel. + /// The new name for the category. /// The options to be used when sending the request. - /// is null. + /// is null. /// - /// The created category channel. + /// A task that represents the asynchronous creation operation. The task result contains the newly created + /// category channel. /// public Task CreateCategoryChannelAsync(string name, RequestOptions options = null) => GuildHelper.CreateCategoryChannelAsync(this, Discord, name, options); @@ -526,11 +574,12 @@ namespace Discord.WebSocket //Invites /// - /// Returns a collection of invites associated with this channel. + /// Gets a collection of all invites in this guild. /// /// The options to be used when sending the request. /// - /// An awaitable containing a collection of invites. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection of + /// invite metadata, each representing information for an invite found within this guild. /// public Task> GetInvitesAsync(RequestOptions options = null) => GuildHelper.GetInvitesAsync(this, Discord, options); @@ -539,18 +588,19 @@ namespace Discord.WebSocket /// /// The options to be used when sending the request. /// - /// A partial metadata of the vanity invite found within this guild. + /// A task that represents the asynchronous get operation. The task result contains the partial metadata of + /// the vanity invite found within this guild; null if none is found. /// public Task GetVanityInviteAsync(RequestOptions options = null) => GuildHelper.GetVanityInviteAsync(this, Discord, options); //Roles /// - /// Gets a role. + /// Gets a role in this guild. /// - /// The snowflake identifier of the role. + /// The snowflake identifier for the role. /// - /// The role associated with the snowflake identifier. + /// A role that is associated with the specified ; null if none is found. /// public SocketRole GetRole(ulong id) { @@ -560,18 +610,17 @@ namespace Discord.WebSocket } /// - /// Creates a role. + /// Creates a new role with the provided name. /// - /// The name of the new role. - /// - /// The permissions that the new role possesses. Set to null to use the default permissions. - /// - /// The color of the role. Set to null to use the default color. - /// Used to determine if users of this role are separated in the user list. + /// The new name for the role. + /// The guild permission that the role should possess. + /// The color of the role. + /// Whether the role is separated from others on the sidebar. /// The options to be used when sending the request. - /// is null. + /// is null. /// - /// The created role. + /// A task that represents the asynchronous creation operation. The task result contains the newly created + /// role. /// public Task CreateRoleAsync(string name, GuildPermissions? permissions = default(GuildPermissions?), Color? color = default(Color?), bool isHoisted = false, RequestOptions options = null) @@ -593,9 +642,16 @@ namespace Discord.WebSocket /// /// Gets a user from this guild. /// - /// The snowflake identifier of the user (e.g. `168693960628371456`). + /// + /// This method retrieves a user found within this guild. + /// + /// This may return null in the WebSocket implementation due to incomplete user collection in + /// large guilds. + /// + /// + /// The snowflake identifier of the user. /// - /// A WebSocket-based guild user associated with the snowflake identifier. + /// A guild user associated with the specified ; null if none is found. /// public SocketGuildUser GetUser(ulong id) { @@ -657,9 +713,7 @@ namespace Discord.WebSocket return null; } - /// - /// Downloads the users of this guild to the WebSocket cache. - /// + /// public async Task DownloadUsersAsync() { await Discord.DownloadUsersAsync(new[] { this }).ConfigureAwait(false); @@ -670,6 +724,15 @@ namespace Discord.WebSocket } //Audit logs + /// + /// Gets the specified number of audit log entries for this guild. + /// + /// The number of audit log entries to fetch. + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous get operation. The task result contains a read-only collection + /// of the requested audit log entries. + /// public IAsyncEnumerable> GetAuditLogsAsync(int limit, RequestOptions options = null) => GuildHelper.GetAuditLogsAsync(this, Discord, null, limit, options); @@ -895,6 +958,9 @@ namespace Discord.WebSocket /// /// Gets the name of the guild. /// + /// + /// A string that resolves to . + /// public override string ToString() => Name; private string DebuggerDisplay => $"{Name} ({Id})"; internal SocketGuild Clone() => MemberwiseClone() as SocketGuild; @@ -1004,7 +1070,8 @@ namespace Discord.WebSocket Task IGuild.GetOwnerAsync(CacheMode mode, RequestOptions options) => Task.FromResult(Owner); - async Task> IGuild.GetAuditLogAsync(int limit, CacheMode cacheMode, RequestOptions options) + /// + async Task> IGuild.GetAuditLogsAsync(int limit, CacheMode cacheMode, RequestOptions options) { if (cacheMode == CacheMode.AllowDownload) return (await GetAuditLogsAsync(limit, options).FlattenAsync().ConfigureAwait(false)).ToImmutableArray(); 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/SocketEntity.cs b/src/Discord.Net.WebSocket/Entities/SocketEntity.cs index c8e14fb6c..f76694e6f 100644 --- a/src/Discord.Net.WebSocket/Entities/SocketEntity.cs +++ b/src/Discord.Net.WebSocket/Entities/SocketEntity.cs @@ -1,4 +1,4 @@ -using System; +using System; namespace Discord.WebSocket { @@ -6,6 +6,7 @@ namespace Discord.WebSocket where T : IEquatable { internal DiscordSocketClient Discord { get; } + /// public T Id { get; } internal SocketEntity(DiscordSocketClient discord, T id) 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; } }