diff --git a/src/Discord.Net.Commands/Results/ExecuteResult.cs b/src/Discord.Net.Commands/Results/ExecuteResult.cs index a1a68866f..055999596 100644 --- a/src/Discord.Net.Commands/Results/ExecuteResult.cs +++ b/src/Discord.Net.Commands/Results/ExecuteResult.cs @@ -3,6 +3,9 @@ using System.Diagnostics; namespace Discord.Commands { + /// + /// Contains information of the command's overall execution result. + /// [DebuggerDisplay(@"{DebuggerDisplay,nq}")] public struct ExecuteResult : IResult { @@ -26,15 +29,56 @@ namespace Discord.Commands ErrorReason = errorReason; } + /// + /// Initializes a new with no error, indicating a successful execution. + /// + /// + /// A that does not contain any errors. + /// public static ExecuteResult FromSuccess() => new ExecuteResult(null, null, null); + /// + /// Initializes a new with a specified and its + /// reason, indicating an unsuccessful execution. + /// + /// The type of error. + /// The reason behind the error. + /// + /// A that contains a and reason. + /// public static ExecuteResult FromError(CommandError error, string reason) => new ExecuteResult(null, error, reason); + /// + /// Initializes a new with a specified exception, indicating an unsuccessful + /// execution. + /// + /// The exception that caused the command execution to fail. + /// + /// A that contains the exception that caused the unsuccessful execution, along + /// with a of type Exception as well as the exception message as the + /// reason. + /// public static ExecuteResult FromError(Exception ex) => new ExecuteResult(ex, CommandError.Exception, ex.Message); + /// + /// Initializes a new with a specified result; this may or may not be an + /// successful execution depending on the and + /// specified. + /// + /// The result to inherit from. + /// + /// A that inherits the error type and reason. + /// public static ExecuteResult FromError(IResult result) => new ExecuteResult(null, result.Error, result.ErrorReason); - + + /// + /// Gets a string that indicates the execution result. + /// + /// + /// Success if is true; otherwise ": + /// ". + /// public override string ToString() => IsSuccess ? "Success" : $"{Error}: {ErrorReason}"; private string DebuggerDisplay => IsSuccess ? "Success" : $"{Error}: {ErrorReason}"; } diff --git a/src/Discord.Net.Commands/Results/IResult.cs b/src/Discord.Net.Commands/Results/IResult.cs index eacea3cfe..c11b58001 100644 --- a/src/Discord.Net.Commands/Results/IResult.cs +++ b/src/Discord.Net.Commands/Results/IResult.cs @@ -1,13 +1,31 @@ namespace Discord.Commands { - /// Represents information of the command execution result. + /// + /// Contains information of the result related to a command. + /// public interface IResult { - /// Describes the error type that may have occurred during the operation. + /// + /// Describes the error type that may have occurred during the operation. + /// + /// + /// A indicating the type of error that may have occurred during the operation; + /// null if the operation was successful. + /// CommandError? Error { get; } - /// Describes the reason for the error. + /// + /// Describes the reason for the error. + /// + /// + /// A string containing the error reason. + /// string ErrorReason { get; } - /// Indicates whether the operation was successful or not. + /// + /// Indicates whether the operation was successful or not. + /// + /// + /// true if the result is positive; otherwise false. + /// bool IsSuccess { get; } } } diff --git a/src/Discord.Net.Commands/Results/ParseResult.cs b/src/Discord.Net.Commands/Results/ParseResult.cs index 0a9f3224a..8e10dc66c 100644 --- a/src/Discord.Net.Commands/Results/ParseResult.cs +++ b/src/Discord.Net.Commands/Results/ParseResult.cs @@ -4,6 +4,9 @@ using System.Diagnostics; namespace Discord.Commands { + /// + /// Contains information for the parsing result from the command service's parser. + /// [DebuggerDisplay(@"{DebuggerDisplay,nq}")] public struct ParseResult : IResult { diff --git a/src/Discord.Net.Core/Entities/Channels/IMessageChannel.cs b/src/Discord.Net.Core/Entities/Channels/IMessageChannel.cs index 146677e27..5e17617b2 100644 --- a/src/Discord.Net.Core/Entities/Channels/IMessageChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IMessageChannel.cs @@ -81,32 +81,105 @@ namespace Discord /// /// Gets the last N messages from this message channel. /// + /// + /// + /// The returned collection is an asynchronous enumerable object; one must call + /// to access the individual messages as a + /// collection. + /// + /// + /// Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual + /// rate limit, causing your bot to freeze! + /// + /// This method will attempt to fetch the number of messages specified under . The + /// library will attempt to split up the requests according to your and + /// . In other words, should the user request 500 messages, + /// and the constant is 100, the request will + /// be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need + /// of flattening. + /// + /// + /// The following example downloads 300 messages and gets messages that belong to the user + /// 53905483156684800. + /// + /// var messages = await messageChannel.GetMessagesAsync(300).FlattenAsync(); + /// var userMessages = messages.Where(x => x.Author.Id == 53905483156684800); + /// + /// /// The numbers of message to be gotten from. - /// 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. /// - /// Paged collection of messages. Flattening the paginated response into a collection of messages with - /// is required if you wish to access the messages. + /// Paged collection of messages. /// IAsyncEnumerable> GetMessagesAsync(int limit = DiscordConfig.MaxMessagesPerBatch, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// /// Gets a collection of messages in this channel. /// + /// + /// + /// The returned collection is an asynchronous enumerable object; one must call + /// to access the individual messages as a + /// collection. + /// + /// + /// Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual + /// rate limit, causing your bot to freeze! + /// + /// This method will attempt to fetch the number of messages specified under around + /// the message depending on the . The library will + /// attempt to split up the requests according to your and + /// . In other words, should the user request 500 messages, + /// and the constant is 100, the request will + /// be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need + /// of flattening. + /// + /// + /// The following example gets 5 message prior to the message identifier 442012544660537354. + /// + /// var messages = await channel.GetMessagesAsync(442012544660537354, Direction.Before, 5).FlattenAsync(); + /// + /// /// 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 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. /// - /// Paged collection of messages. Flattening the paginated response into a collection of messages with - /// is required if you wish to access the messages. + /// Paged collection of messages. /// 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. /// + /// + /// + /// The returned collection is an asynchronous enumerable object; one must call + /// to access the individual messages as a + /// collection. + /// + /// + /// Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual + /// rate limit, causing your bot to freeze! + /// + /// This method will attempt to fetch the number of messages specified under around + /// the message depending on the . The library will + /// attempt to split up the requests according to your and + /// . In other words, should the user request 500 messages, + /// and the constant is 100, the request will + /// be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need + /// of flattening. + /// + /// + /// The following example gets 5 message prior to a specific message, oldMessage. + /// + /// var messages = await channel.GetMessagesAsync(oldMessage, Direction.Before, 5).FlattenAsync(); + /// + /// /// 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. @@ -114,8 +187,7 @@ namespace Discord /// cache. /// 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. + /// Paged collection of messages. /// IAsyncEnumerable> GetMessagesAsync(IMessage fromMessage, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); @@ -158,6 +230,15 @@ namespace Discord /// Continuously broadcasts the "user is typing" message to all users in this channel until the returned /// object is disposed. /// + /// + /// The following example keeps the client in the typing state until LongRunningAsync has finished. + /// + /// using (messageChannel.EnterTypingState()) + /// { + /// await LongRunningAsync(); + /// } + /// + /// /// 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 diff --git a/src/Discord.Net.Core/Entities/Channels/ITextChannel.cs b/src/Discord.Net.Core/Entities/Channels/ITextChannel.cs index 2b5da5b2f..1f5496257 100644 --- a/src/Discord.Net.Core/Entities/Channels/ITextChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/ITextChannel.cs @@ -29,6 +29,13 @@ namespace Discord /// /// Bulk-deletes multiple messages. /// + /// + /// The following example gets 250 messages from the channel and deletes them. + /// + /// var messages = await textChannel.GetMessagesAsync(250).FlattenAsync(); + /// await textChannel.DeleteMessagesAsync(messages); + /// + /// /// /// This method attempts to remove the messages specified in bulk. /// diff --git a/src/Discord.Net.Rest/Entities/Channels/IRestMessageChannel.cs b/src/Discord.Net.Rest/Entities/Channels/IRestMessageChannel.cs index 30e4ddf2c..42ca20f7c 100644 --- a/src/Discord.Net.Rest/Entities/Channels/IRestMessageChannel.cs +++ b/src/Discord.Net.Rest/Entities/Channels/IRestMessageChannel.cs @@ -78,35 +78,109 @@ namespace Discord.Rest /// /// Gets the last N messages from this message channel. /// + /// + /// + /// The returned collection is an asynchronous enumerable object; one must call + /// to access the individual messages as a + /// collection. + /// + /// + /// Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual + /// rate limit, causing your bot to freeze! + /// + /// This method will attempt to fetch the number of messages specified under . The + /// library will attempt to split up the requests according to your and + /// . In other words, should the user request 500 messages, + /// and the constant is 100, the request will + /// be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need + /// of flattening. + /// + /// + /// The following example downloads 300 messages and gets messages that belong to the user + /// 53905483156684800. + /// + /// var messages = await messageChannel.GetMessagesAsync(300).FlattenAsync(); + /// var userMessages = messages.Where(x => x.Author.Id == 53905483156684800); + /// + /// /// 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. + /// Paged collection of messages. /// IAsyncEnumerable> GetMessagesAsync(int limit = DiscordConfig.MaxMessagesPerBatch, RequestOptions options = null); /// /// Gets a collection of messages in this channel. /// + /// + /// + /// The returned collection is an asynchronous enumerable object; one must call + /// to access the individual messages as a + /// collection. + /// + /// + /// Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual + /// rate limit, causing your bot to freeze! + /// + /// This method will attempt to fetch the number of messages specified under around + /// the message depending on the . The library will + /// attempt to split up the requests according to your and + /// . In other words, should the user request 500 messages, + /// and the constant is 100, the request will + /// be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need + /// of flattening. + /// + /// + /// The following example gets 5 message prior to the message identifier 442012544660537354. + /// + /// var messages = await channel.GetMessagesAsync(442012544660537354, Direction.Before, 5).FlattenAsync(); + /// + /// /// 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 that determines whether the object should be fetched from + /// cache. /// 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. + /// Paged collection of messages. /// IAsyncEnumerable> GetMessagesAsync(ulong fromMessageId, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch, RequestOptions options = null); /// /// Gets a collection of messages in this channel. /// + /// + /// + /// The returned collection is an asynchronous enumerable object; one must call + /// to access the individual messages as a + /// collection. + /// + /// + /// Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual + /// rate limit, causing your bot to freeze! + /// + /// This method will attempt to fetch the number of messages specified under around + /// the message depending on the . The library will + /// attempt to split up the requests according to your and + /// . In other words, should the user request 500 messages, + /// and the constant is 100, the request will + /// be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need + /// of flattening. + /// + /// + /// The following example gets 5 message prior to a specific message, oldMessage. + /// + /// var messages = await channel.GetMessagesAsync(oldMessage, Direction.Before, 5).FlattenAsync(); + /// + /// /// 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 that determines whether the object should be fetched from + /// cache. /// 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. + /// Paged collection of messages. /// IAsyncEnumerable> GetMessagesAsync(IMessage fromMessage, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch, RequestOptions options = null); /// diff --git a/src/Discord.Net.WebSocket/Entities/Channels/SocketDMChannel.cs b/src/Discord.Net.WebSocket/Entities/Channels/SocketDMChannel.cs index 7fc153bfe..6b6577167 100644 --- a/src/Discord.Net.WebSocket/Entities/Channels/SocketDMChannel.cs +++ b/src/Discord.Net.WebSocket/Entities/Channels/SocketDMChannel.cs @@ -75,41 +75,109 @@ namespace Discord.WebSocket } /// - /// Gets the last N messages from this channel. + /// Gets the last N messages from this message channel. /// - /// The number of messages to get. + /// + /// + /// The returned collection is an asynchronous enumerable object; one must call + /// to access the individual messages as a + /// collection. + /// + /// + /// Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual + /// rate limit, causing your bot to freeze! + /// + /// This method will attempt to fetch the number of messages specified under . The + /// library will attempt to split up the requests according to your and + /// . In other words, should the user request 500 messages, + /// and the constant is 100, the request will + /// be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need + /// of flattening. + /// + /// + /// The following example downloads 300 messages and gets messages that belong to the user + /// 53905483156684800. + /// + /// var messages = await messageChannel.GetMessagesAsync(300).FlattenAsync(); + /// var userMessages = messages.Where(x => x.Author.Id == 53905483156684800); + /// + /// + /// 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. + /// Paged collection of messages. /// public IAsyncEnumerable> GetMessagesAsync(int limit = DiscordConfig.MaxMessagesPerBatch, RequestOptions options = null) => SocketChannelHelper.GetMessagesAsync(this, Discord, _messages, null, Direction.Before, limit, CacheMode.AllowDownload, options); - /// /// Gets a collection of messages in this channel. /// + /// + /// + /// The returned collection is an asynchronous enumerable object; one must call + /// to access the individual messages as a + /// collection. + /// + /// + /// Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual + /// rate limit, causing your bot to freeze! + /// + /// This method will attempt to fetch the number of messages specified under around + /// the message depending on the . The library will + /// attempt to split up the requests according to your and + /// . In other words, should the user request 500 messages, + /// and the constant is 100, the request will + /// be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need + /// of flattening. + /// + /// + /// The following example gets 5 message prior to the message identifier 442012544660537354. + /// + /// var messages = await channel.GetMessagesAsync(442012544660537354, Direction.Before, 5).FlattenAsync(); + /// + /// /// 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. + /// Paged collection of 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 returned collection is an asynchronous enumerable object; one must call + /// to access the individual messages as a + /// collection. + /// + /// + /// Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual + /// rate limit, causing your bot to freeze! + /// + /// This method will attempt to fetch the number of messages specified under around + /// the message depending on the . The library will + /// attempt to split up the requests according to your and + /// . In other words, should the user request 500 messages, + /// and the constant is 100, the request will + /// be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need + /// of flattening. + /// + /// + /// The following example gets 5 message prior to a specific message, oldMessage. + /// + /// var messages = await channel.GetMessagesAsync(oldMessage, Direction.Before, 5).FlattenAsync(); + /// + /// /// 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. + /// Paged collection of 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); diff --git a/src/Discord.Net.WebSocket/Entities/Channels/SocketTextChannel.cs b/src/Discord.Net.WebSocket/Entities/Channels/SocketTextChannel.cs index bf87c48a8..59e9933c3 100644 --- a/src/Discord.Net.WebSocket/Entities/Channels/SocketTextChannel.cs +++ b/src/Discord.Net.WebSocket/Entities/Channels/SocketTextChannel.cs @@ -92,37 +92,108 @@ namespace Discord.WebSocket /// /// Gets the last N messages from this message channel. /// + /// + /// + /// The returned collection is an asynchronous enumerable object; one must call + /// to access the individual messages as a + /// collection. + /// + /// + /// Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual + /// rate limit, causing your bot to freeze! + /// + /// This method will attempt to fetch the number of messages specified under . The + /// library will attempt to split up the requests according to your and + /// . In other words, should the user request 500 messages, + /// and the constant is 100, the request will + /// be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need + /// of flattening. + /// + /// + /// The following example downloads 300 messages and gets messages that belong to the user + /// 53905483156684800. + /// + /// var messages = await messageChannel.GetMessagesAsync(300).FlattenAsync(); + /// var userMessages = messages.Where(x => x.Author.Id == 53905483156684800); + /// + /// /// 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. + /// Paged collection of messages. /// + public IAsyncEnumerable> GetMessagesAsync(int limit = DiscordConfig.MaxMessagesPerBatch, RequestOptions options = null) => SocketChannelHelper.GetMessagesAsync(this, Discord, _messages, null, Direction.Before, limit, CacheMode.AllowDownload, options); /// /// Gets a collection of messages in this channel. /// + /// + /// + /// The returned collection is an asynchronous enumerable object; one must call + /// to access the individual messages as a + /// collection. + /// + /// + /// Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual + /// rate limit, causing your bot to freeze! + /// + /// This method will attempt to fetch the number of messages specified under around + /// the message depending on the . The library will + /// attempt to split up the requests according to your and + /// . In other words, should the user request 500 messages, + /// and the constant is 100, the request will + /// be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need + /// of flattening. + /// + /// + /// The following example gets 5 message prior to the message identifier 442012544660537354. + /// + /// var messages = await channel.GetMessagesAsync(442012544660537354, Direction.Before, 5).FlattenAsync(); + /// + /// /// 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. + /// Paged collection of 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 returned collection is an asynchronous enumerable object; one must call + /// to access the individual messages as a + /// collection. + /// + /// + /// Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual + /// rate limit, causing your bot to freeze! + /// + /// This method will attempt to fetch the number of messages specified under around + /// the message depending on the . The library will + /// attempt to split up the requests according to your and + /// . In other words, should the user request 500 messages, + /// and the constant is 100, the request will + /// be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need + /// of flattening. + /// + /// + /// The following example gets 5 message prior to a specific message, oldMessage. + /// + /// var messages = await channel.GetMessagesAsync(oldMessage, Direction.Before, 5).FlattenAsync(); + /// + /// /// 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. + /// Paged collection of 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);