diff --git a/src/Discord.Net.Core/Entities/ISnowflakeEntity.cs b/src/Discord.Net.Core/Entities/ISnowflakeEntity.cs index 9c7b3721f..6f2c7512b 100644 --- a/src/Discord.Net.Core/Entities/ISnowflakeEntity.cs +++ b/src/Discord.Net.Core/Entities/ISnowflakeEntity.cs @@ -6,7 +6,7 @@ namespace Discord public interface ISnowflakeEntity : IEntity { /// - /// Gets when the snowflake is created. + /// Gets when the snowflake was created. /// /// /// A representing when the entity was first created. diff --git a/src/Discord.Net.Rest/Entities/Channels/RestDMChannel.cs b/src/Discord.Net.Rest/Entities/Channels/RestDMChannel.cs index ddb4f9b10..bee096273 100644 --- a/src/Discord.Net.Rest/Entities/Channels/RestDMChannel.cs +++ b/src/Discord.Net.Rest/Entities/Channels/RestDMChannel.cs @@ -15,9 +15,19 @@ namespace Discord.Rest [DebuggerDisplay(@"{DebuggerDisplay,nq}")] public class RestDMChannel : RestChannel, IDMChannel, IRestPrivateChannel, IRestMessageChannel { + /// + /// Gets the current logged-in user. + /// public RestUser CurrentUser { get; } + + /// + /// Gets the recipient of the channel. + /// public RestUser Recipient { get; } + /// + /// Gets a collection that is the current logged-in user and the recipient. + /// public IReadOnlyCollection Users => ImmutableArray.Create(CurrentUser, Recipient); internal RestDMChannel(BaseDiscordClient discord, ulong id, ulong recipientId) @@ -132,6 +142,12 @@ namespace Discord.Rest public IDisposable EnterTypingState(RequestOptions options = null) => ChannelHelper.EnterTypingState(this, Discord, options); + /// + /// Gets a string that represents the Username#Discriminator of the recipient. + /// + /// + /// A string that resolves to the Recipient of this channel. + /// public override string ToString() => $"@{Recipient}"; private string DebuggerDisplay => $"@{Recipient} ({Id}, DM)"; diff --git a/src/Discord.Net.Rest/Entities/Guilds/RestGuild.cs b/src/Discord.Net.Rest/Entities/Guilds/RestGuild.cs index 0d1b20680..3c75afd6a 100644 --- a/src/Discord.Net.Rest/Entities/Guilds/RestGuild.cs +++ b/src/Discord.Net.Rest/Entities/Guilds/RestGuild.cs @@ -59,7 +59,14 @@ namespace Discord.Rest /// public string SplashUrl => CDN.GetGuildSplashUrl(Id, SplashId); + /// + /// Gets the built-in role containing all users in this guild. + /// public RestRole EveryoneRole => GetRole(Id); + + /// + /// Gets a collection of all roles in this guild. + /// public IReadOnlyCollection Roles => _roles.ToReadOnlyCollection(); /// public IReadOnlyCollection Emotes => _emotes; @@ -170,10 +177,38 @@ namespace Discord.Rest => GuildHelper.LeaveAsync(this, Discord, options); //Bans + //Bans + /// + /// Gets a collection of all users banned in this guild. + /// + /// 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 + /// 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); @@ -192,36 +227,110 @@ namespace Discord.Rest => GuildHelper.RemoveBanAsync(this, Discord, userId, options); //Channels + /// + /// Gets a collection of all channels in this guild. + /// + /// 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 + /// generic channels found within this guild. + /// public Task> GetChannelsAsync(RequestOptions options = null) => GuildHelper.GetChannelsAsync(this, Discord, options); + + /// + /// Gets a channel in this guild. + /// + /// The snowflake identifier for the channel. + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous get operation. The task result contains the generic channel + /// associated with the specified ; null if none is found. + /// public Task GetChannelAsync(ulong id, RequestOptions options = null) => GuildHelper.GetChannelAsync(this, Discord, id, options); + + /// + /// Gets a text channel in this guild. + /// + /// The snowflake identifier for the text channel. + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous get operation. The task result contains the text channel + /// associated with the specified ; null if none is found. + /// public async Task GetTextChannelAsync(ulong id, RequestOptions options = null) { var channel = await GuildHelper.GetChannelAsync(this, Discord, id, options).ConfigureAwait(false); return channel as RestTextChannel; } + + /// + /// Gets a collection of all text channels in this guild. + /// + /// The that determines whether the object should be fetched from cache. + /// 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 + /// message channels found within this guild. + /// public async Task> GetTextChannelsAsync(RequestOptions options = null) { var channels = await GuildHelper.GetChannelsAsync(this, Discord, options).ConfigureAwait(false); return channels.Select(x => x as RestTextChannel).Where(x => x != null).ToImmutableArray(); } + + /// + /// Gets a voice channel in this guild. + /// + /// The snowflake identifier for the voice channel. + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous get operation. The task result contains the voice channel associated + /// with the specified ; null if none is found. + /// public async Task GetVoiceChannelAsync(ulong id, RequestOptions options = null) { var channel = await GuildHelper.GetChannelAsync(this, Discord, id, options).ConfigureAwait(false); return channel as RestVoiceChannel; } + + /// + /// Gets a collection of all voice channels in this guild. + /// + /// 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 + /// voice channels found within this guild. + /// public async Task> GetVoiceChannelsAsync(RequestOptions options = null) { var channels = await GuildHelper.GetChannelsAsync(this, Discord, options).ConfigureAwait(false); return channels.Select(x => x as RestVoiceChannel).Where(x => x != null).ToImmutableArray(); } + + /// + /// Gets a collection of all category channels in this guild. + /// + /// 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 + /// category channels found within this guild. + /// public async Task> GetCategoryChannelsAsync(RequestOptions options = null) { var channels = await GuildHelper.GetChannelsAsync(this, Discord, options).ConfigureAwait(false); return channels.Select(x => x as RestCategoryChannel).Where(x => x != null).ToImmutableArray(); } + /// + /// Gets the AFK voice channel in this guild. + /// + /// The options to be used when sending the request. + /// + /// 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. + /// public async Task GetAFKChannelAsync(RequestOptions options = null) { var afkId = AFKChannelId; @@ -232,6 +341,15 @@ namespace Discord.Rest } return null; } + + /// + /// Gets the first viewable text channel in this guild. + /// + /// The options to be used when sending the request. + /// + /// 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. + /// public async Task GetDefaultChannelAsync(RequestOptions options = null) { var channels = await GetTextChannelsAsync(options).ConfigureAwait(false); @@ -241,6 +359,15 @@ namespace Discord.Rest .OrderBy(c => c.Position) .FirstOrDefault(); } + + /// + /// Gets the embed channel (i.e. the channel set in the guild's widget settings) in this guild. + /// + /// The options to be used when sending the request. + /// + /// 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. + /// public async Task GetEmbedChannelAsync(RequestOptions options = null) { var embedId = EmbedChannelId; @@ -248,6 +375,15 @@ namespace Discord.Rest return await GuildHelper.GetChannelAsync(this, Discord, embedId.Value, options).ConfigureAwait(false); return null; } + + /// + /// Gets the first viewable text channel in this guild. + /// + /// The options to be used when sending the request. + /// + /// 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. + /// public async Task GetSystemChannelAsync(RequestOptions options = null) { var systemId = SystemChannelId; @@ -301,6 +437,14 @@ namespace Discord.Rest => GuildHelper.CreateIntegrationAsync(this, Discord, id, type, options); //Invites + /// + /// Gets a collection of all invites in this guild. + /// + /// 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 + /// invite metadata, each representing information for an invite found within this guild. + /// public Task> GetInvitesAsync(RequestOptions options = null) => GuildHelper.GetInvitesAsync(this, Discord, options); /// @@ -314,6 +458,13 @@ namespace Discord.Rest => GuildHelper.GetVanityInviteAsync(this, Discord, options); //Roles + /// + /// Gets a role in this guild. + /// + /// The snowflake identifier for the role. + /// + /// A role that is associated with the specified ; null if none is found. + /// public RestRole GetRole(ulong id) { if (_roles.TryGetValue(id, out RestRole value)) @@ -321,6 +472,18 @@ namespace Discord.Rest return null; } + /// + /// Creates a new role with the provided name. + /// + /// 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. + /// + /// A task that represents the asynchronous creation operation. The task result contains the newly created + /// role. + /// public async Task CreateRoleAsync(string name, GuildPermissions? permissions = default(GuildPermissions?), Color? color = default(Color?), bool isHoisted = false, RequestOptions options = null) { @@ -330,26 +493,113 @@ namespace Discord.Rest } //Users + /// + /// Gets a collection of all users in this guild. + /// + /// + /// This method retrieves all users found within this guild. + /// + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous get operation. The task result contains a collection of guild + /// users found within this guild. + /// public IAsyncEnumerable> GetUsersAsync(RequestOptions options = null) => GuildHelper.GetUsersAsync(this, Discord, null, null, options); + + /// + /// Gets a user from this guild. + /// + /// + /// This method retrieves a user found within this guild. + /// + /// The snowflake identifier of the user. + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous get operation. The task result contains the guild user + /// associated with the specified ; null if none is found. + /// public Task GetUserAsync(ulong id, RequestOptions options = null) => GuildHelper.GetUserAsync(this, Discord, id, options); + + /// + /// Gets the current user for this guild. + /// + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous get operation. The task result contains the currently logged-in + /// user within this guild. + /// public Task GetCurrentUserAsync(RequestOptions options = null) => GuildHelper.GetUserAsync(this, Discord, Discord.CurrentUser.Id, options); + + /// + /// Gets the owner of this guild. + /// + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous get operation. The task result contains the owner of this guild. + /// public Task GetOwnerAsync(RequestOptions options = null) => GuildHelper.GetUserAsync(this, Discord, OwnerId, options); /// + /// + /// Prunes inactive users. + /// + /// + /// + /// 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. + /// + /// 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. + /// public Task PruneUsersAsync(int days = 30, bool simulate = false, RequestOptions options = null) => GuildHelper.PruneUsersAsync(this, Discord, days, simulate, options); //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); //Webhooks + /// + /// Gets a webhook found within this guild. + /// + /// The identifier for the webhook. + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous get operation. The task result contains the webhook with the + /// specified ; null if none is found. + /// public Task GetWebhookAsync(ulong id, RequestOptions options = null) => GuildHelper.GetWebhookAsync(this, Discord, id, options); + + /// + /// Gets a collection of all webhook from this guild. + /// + /// 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 webhooks found within the guild. + /// public Task> GetWebhooksAsync(RequestOptions options = null) => GuildHelper.GetWebhooksAsync(this, Discord, options); diff --git a/src/Discord.Net.Rest/Entities/Invites/RestInvite.cs b/src/Discord.Net.Rest/Entities/Invites/RestInvite.cs index e498295cc..153eb6c41 100644 --- a/src/Discord.Net.Rest/Entities/Invites/RestInvite.cs +++ b/src/Discord.Net.Rest/Entities/Invites/RestInvite.cs @@ -62,6 +62,12 @@ namespace Discord.Rest public Task DeleteAsync(RequestOptions options = null) => InviteHelper.DeleteAsync(this, Discord, options); + /// + /// Gets the URL of the invite. + /// + /// + /// A string that resolves to the Url of the invite. + /// public override string ToString() => Url; private string DebuggerDisplay => $"{Url} ({GuildName} / {ChannelName})"; diff --git a/src/Discord.Net.Rest/Entities/Users/RestUser.cs b/src/Discord.Net.Rest/Entities/Users/RestUser.cs index e08f500c4..f6a555b6d 100644 --- a/src/Discord.Net.Rest/Entities/Users/RestUser.cs +++ b/src/Discord.Net.Rest/Entities/Users/RestUser.cs @@ -65,6 +65,13 @@ namespace Discord.Rest Update(model); } + /// + /// Returns a direct message channel to this user, or create one if it does not already exist. + /// + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous get operation. The task result contains a rest DM channel where the user is the recipient. + /// public Task GetOrCreateDMChannelAsync(RequestOptions options = null) => UserHelper.CreateDMChannelAsync(this, Discord, options); @@ -80,7 +87,7 @@ namespace Discord.Rest /// Gets the Username#Descriminator of the user. /// /// - /// A string that is the Username#Descriminator of the user. + /// A string that resolves to Username#Descriminator of the user. /// public override string ToString() => $"{Username}#{Discriminator}"; private string DebuggerDisplay => $"{Username}#{Discriminator} ({Id}{(IsBot ? ", Bot" : "")})"; diff --git a/src/Discord.Net.WebSocket/Entities/Channels/SocketDMChannel.cs b/src/Discord.Net.WebSocket/Entities/Channels/SocketDMChannel.cs index c0a042669..7fc153bfe 100644 --- a/src/Discord.Net.WebSocket/Entities/Channels/SocketDMChannel.cs +++ b/src/Discord.Net.WebSocket/Entities/Channels/SocketDMChannel.cs @@ -25,6 +25,10 @@ namespace Discord.WebSocket /// public IReadOnlyCollection CachedMessages => _messages?.Messages ?? ImmutableArray.Create(); + + /// + /// Gets a collection that is the current logged-in user and the recipient. + /// public new IReadOnlyCollection Users => ImmutableArray.Create(Discord.CurrentUser, Recipient); internal SocketDMChannel(DiscordSocketClient discord, ulong id, SocketGlobalUser recipient) @@ -81,8 +85,32 @@ 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); ///