diff --git a/src/Discord.Net.Core/Entities/Roles/Color.cs b/src/Discord.Net.Core/Entities/Roles/Color.cs index f24ac883e..b2f29d110 100644 --- a/src/Discord.Net.Core/Entities/Roles/Color.cs +++ b/src/Discord.Net.Core/Entities/Roles/Color.cs @@ -66,8 +66,15 @@ namespace Discord public byte B => (byte)(RawValue); /// - /// Initializes a struct with the given raw value. + /// Initializes a with the given raw value. /// + /// + /// The following will create a color that has a hex value of + /// #607D8B. + /// + /// Color darkGrey = new Color(0x607D8B); + /// + /// /// The raw value of the color (e.g. 0x607D8B). public Color(uint rawValue) { @@ -76,6 +83,13 @@ namespace Discord /// /// Initializes a struct with the given RGB bytes. /// + /// + /// The following will create a color that has a value of + /// #607D8B. + /// + /// Color darkGrey = new Color((byte)0b_01100000, (byte)0b_01111101, (byte)0b_10001011); + /// + /// /// The byte that represents the red color. /// The byte that represents the green color. /// The byte that represents the blue color. @@ -90,6 +104,13 @@ namespace Discord /// /// Initializes a struct with the given RGB value. /// + /// + /// The following will create a color that has a value of + /// #607D8B. + /// + /// Color darkGrey = new Color(96, 125, 139); + /// + /// /// The value that represents the red color. Must be within 0~255. /// The value that represents the green color. Must be within 0~255. /// The value that represents the blue color. Must be within 0~255. @@ -110,6 +131,13 @@ namespace Discord /// /// Initializes a struct with the given RGB float value. /// + /// + /// The following will create a color that has a value of + /// #607c8c. + /// + /// Color darkGrey = new Color(0.38f, 0.49f, 0.55f); + /// + /// /// The value that represents the red color. Must be within 0~1. /// The value that represents the green color. Must be within 0~1. /// The value that represents the blue color. Must be within 0~1. diff --git a/src/Discord.Net.Core/IDiscordClient.cs b/src/Discord.Net.Core/IDiscordClient.cs index f5bbd0a28..da9ef3d6d 100644 --- a/src/Discord.Net.Core/IDiscordClient.cs +++ b/src/Discord.Net.Core/IDiscordClient.cs @@ -23,7 +23,26 @@ namespace Discord /// TokenType TokenType { get; } + /// + /// Starts the connection between Discord and the client.. + /// + /// + /// This method will initialize the connection between the client and Discord. + /// + /// This method will immediately return after it is called, as it will initialize the connection on + /// another thread. + /// + /// + /// + /// An awaitable . + /// Task StartAsync(); + /// + /// Stops the connection between Discord and the client. + /// + /// + /// An awaitable . + /// Task StopAsync(); /// @@ -40,24 +59,52 @@ namespace Discord Task GetApplicationInfoAsync(RequestOptions options = null); /// - /// Gets a generic channel with the provided ID. + /// Gets a generic channel via the snowflake identifier. /// - /// The ID of the channel. - /// The that determines whether the object should be fetched from cache. + /// + /// + /// var channel = await _client.GetChannelAsync(381889909113225237); + /// if (channel != null && channel is IMessageChannel msgChannel) + /// { + /// await msgChannel.SendMessageAsync($"{msgChannel} is created at {msgChannel.CreatedAt}"); + /// } + /// + /// + /// The snowflake identifier of the channel (e.g. `381889909113225237`). + /// + /// The that determines whether the object should be fetched from cache. + /// + /// The options to be used when sending the request. + /// + /// An awaitable containing the channel associated with the snowflake identifier. + /// Task GetChannelAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// - /// Gets a list of private channels. + /// Gets a collection of private channels opened in this session. /// /// /// The that determines whether the object should be fetched from cache. /// + /// The options to be used when sending the request. + /// + /// This method will retrieve all private channels (including direct-message, group channel and such) that + /// are currently opened in this session. + /// + /// This method will not return previously opened private channels outside of the current session! If + /// you have just started the client, this may return an empty collection. + /// + /// + /// + /// An awaitable containing a collection of private channels that have been opened in + /// this session. + /// Task> GetPrivateChannelsAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// - /// Returns a collection of direct message channels. + /// Gets a collection of direct message channels opened in this session. /// /// /// This method returns a collection of currently opened direct message channels. - /// + /// /// This method will not return previously opened DM channels outside of the current session! If you /// have just started the client, this may return an empty collection. /// @@ -65,16 +112,30 @@ 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 a collection of DM channels. + /// An awaitable containing a collection of DM channels that have been opened in this + /// session. /// Task> GetDMChannelsAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// - /// Gets a list of group channels. + /// Gets a collection of group channels opened in this session. /// + /// + /// This method returns a collection of currently opened group channels. + /// + /// This method will not return previously opened group channels outside of the current session! If you + /// have just started the client, this may return an empty collection. + /// + /// /// /// 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 group channels that have been opened in this + /// session. + /// Task> GetGroupChannelsAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); Task> GetConnectionsAsync(RequestOptions options = null); @@ -85,7 +146,41 @@ namespace Discord Task GetInviteAsync(string inviteId, bool withCount = false, RequestOptions options = null); + /// + /// Gets a user via the snowflake identifier. + /// + /// + /// + /// var user = await _client.GetUserAsync(168693960628371456); + /// if (user != null) + /// Console.WriteLine($"{user} is created at {user.CreatedAt}."; + /// + /// + /// 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 the fetched user; null if none is found. + /// Task GetUserAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); + /// + /// Gets a user via the username and discriminator combo. + /// + /// + /// + /// var user = await _client.GetUserAsync("Still", "2876"); + /// if (user != null) + /// Console.WriteLine($"{user} is created at {user.CreatedAt}."; + /// + /// + /// The name of the user (e.g. `Still`). + /// The discriminator value of the user (e.g. `2876`). + /// The options to be used when sending the request. + /// + /// An awaitable containing the fetched user; null if none is found. + /// Task GetUserAsync(string username, string discriminator, RequestOptions options = null); Task> GetVoiceRegionsAsync(RequestOptions options = null); @@ -93,6 +188,14 @@ namespace Discord Task GetWebhookAsync(ulong id, RequestOptions options = null); + /// + /// Gets the recommended shard count as suggested by Discord. + /// + /// The options to be used when sending the request. + /// + /// An awaitable containing an that represents the number of shards + /// that should be used with this account. + /// Task GetRecommendedShardCountAsync(RequestOptions options = null); } } diff --git a/src/Discord.Net.Rest/Entities/Guilds/RestGuild.cs b/src/Discord.Net.Rest/Entities/Guilds/RestGuild.cs index e003e2130..560f7b629 100644 --- a/src/Discord.Net.Rest/Entities/Guilds/RestGuild.cs +++ b/src/Discord.Net.Rest/Entities/Guilds/RestGuild.cs @@ -258,10 +258,39 @@ namespace Discord.Rest } return null; } + /// + /// Creates a text channel with the provided name. + /// + /// The name of the new channel. + /// The options to be used when sending the request. + /// The delegate containing the properties to be applied to the channel upon its creation. + /// is null. + /// + /// The 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. + /// + /// The name of the new 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. + /// + /// The 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. + /// + /// The name of the new channel. + /// The options to be used when sending the request. + /// is null. + /// + /// The created category channel. + /// public Task CreateCategoryChannelAsync(string name, RequestOptions options = null) => GuildHelper.CreateCategoryChannelAsync(this, Discord, name, options); diff --git a/src/Discord.Net.WebSocket/BaseSocketClient.cs b/src/Discord.Net.WebSocket/BaseSocketClient.cs index e9d30a30d..ad00a49b4 100644 --- a/src/Discord.Net.WebSocket/BaseSocketClient.cs +++ b/src/Discord.Net.WebSocket/BaseSocketClient.cs @@ -6,6 +6,9 @@ using Discord.Rest; namespace Discord.WebSocket { + /// + /// Represents the base of a WebSocket-based Discord client. + /// public abstract partial class BaseSocketClient : BaseDiscordClient, IDiscordClient { protected readonly DiscordSocketConfig BaseConfig; diff --git a/src/Discord.Net.WebSocket/DiscordSocketClient.Events.cs b/src/Discord.Net.WebSocket/DiscordSocketClient.Events.cs index 1222b270e..51dea5f9f 100644 --- a/src/Discord.Net.WebSocket/DiscordSocketClient.Events.cs +++ b/src/Discord.Net.WebSocket/DiscordSocketClient.Events.cs @@ -1,8 +1,9 @@ -using System; +using System; using System.Threading.Tasks; +using Discord.API; namespace Discord.WebSocket -{ +{ public partial class DiscordSocketClient { //General @@ -34,5 +35,9 @@ namespace Discord.WebSocket remove { _latencyUpdatedEvent.Remove(value); } } private readonly AsyncEvent> _latencyUpdatedEvent = new AsyncEvent>(); + + internal DiscordSocketClient(DiscordSocketConfig config, DiscordRestApiClient client) : base(config, client) + { + } } } diff --git a/src/Discord.Net.WebSocket/DiscordSocketClient.cs b/src/Discord.Net.WebSocket/DiscordSocketClient.cs index a373829fb..f3d2d5b84 100644 --- a/src/Discord.Net.WebSocket/DiscordSocketClient.cs +++ b/src/Discord.Net.WebSocket/DiscordSocketClient.cs @@ -19,6 +19,9 @@ using GameModel = Discord.API.Game; namespace Discord.WebSocket { + /// + /// Represents a WebSocket-based Discord client. + /// public partial class DiscordSocketClient : BaseSocketClient, IDiscordClient { private readonly ConcurrentQueue _largeGuilds; @@ -66,16 +69,47 @@ namespace Discord.WebSocket public override IReadOnlyCollection Guilds => State.Guilds; /// public override IReadOnlyCollection PrivateChannels => State.PrivateChannels; + /// + /// Gets a collection of direct message channels opened in this session. + /// + /// + /// This method returns a collection of currently opened direct message channels. + /// + /// This method will not return previously opened DM channels outside of the current session! If you + /// have just started the client, this may return an empty collection. + /// + /// + /// + /// An collection of DM channels that have been opened in this session. + /// public IReadOnlyCollection DMChannels => State.PrivateChannels.Select(x => x as SocketDMChannel).Where(x => x != null).ToImmutableArray(); + /// + /// Gets a collection of group channels opened in this session. + /// + /// + /// This method returns a collection of currently opened group channels. + /// + /// This method will not return previously opened group channels outside of the current session! If you + /// have just started the client, this may return an empty collection. + /// + /// + /// + /// An collection of group channels that have been opened in this session. + /// public IReadOnlyCollection GroupChannels => State.PrivateChannels.Select(x => x as SocketGroupChannel).Where(x => x != null).ToImmutableArray(); /// public override IReadOnlyCollection VoiceRegions => _voiceRegions.ToReadOnlyCollection(); - /// Creates a new REST/WebSocket Discord client. + /// + /// Initializes a new REST/WebSocket-based Discord client. + /// public DiscordSocketClient() : this(new DiscordSocketConfig()) { } - /// Creates a new REST/WebSocket Discord client. + /// + /// Initializes a new REST/WebSocket-based Discord client with the provided configuration. + /// + /// The configuration to be used with the client. public DiscordSocketClient(DiscordSocketConfig config) : this(config, CreateApiClient(config), null, null) { } internal DiscordSocketClient(DiscordSocketConfig config, SemaphoreSlim groupLock, DiscordSocketClient parentClient) : this(config, CreateApiClient(config), groupLock, parentClient) { } private DiscordSocketClient(DiscordSocketConfig config, API.DiscordSocketApiClient client, SemaphoreSlim groupLock, DiscordSocketClient parentClient) diff --git a/src/Discord.Net.WebSocket/Entities/Guilds/SocketGuild.cs b/src/Discord.Net.WebSocket/Entities/Guilds/SocketGuild.cs index 689ce145b..ac9ed999c 100644 --- a/src/Discord.Net.WebSocket/Entities/Guilds/SocketGuild.cs +++ b/src/Discord.Net.WebSocket/Entities/Guilds/SocketGuild.cs @@ -54,8 +54,8 @@ namespace Discord.WebSocket /// Gets the number of members. /// /// - /// The number of members is returned by Discord and is the most accurate. You may see discrepancy between - /// the collection and this. + /// 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. /// public int MemberCount { get; internal set; } /// Gets the number of members downloaded to the local guild cache. @@ -98,15 +98,19 @@ namespace Discord.WebSocket /// Gets the first viewable text channel. /// /// - /// This property does not guarantee the user can send message to it. + /// 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. /// public SocketTextChannel DefaultChannel => TextChannels .Where(c => CurrentUser.GetPermissions(c).ViewChannel) .OrderBy(c => c.Position) .FirstOrDefault(); /// - /// Gets the AFK voice channel, or null if none is set. + /// 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. + /// public SocketVoiceChannel AFKChannel { get @@ -116,8 +120,11 @@ namespace Discord.WebSocket } } /// - /// Gets the embed channel set in the widget settings of this guild, or null if none is set. + /// Gets the embed channel set in the widget settings of this guild. /// + /// + /// A channel set in the widget settings of this guild; otherwise null if none is set. + /// public SocketGuildChannel EmbedChannel { get @@ -127,8 +134,12 @@ namespace Discord.WebSocket } } /// - /// Gets the channel where randomized welcome messages are sent, or null if none is set. + /// Gets the channel where randomized welcome messages are sent. /// + /// + /// A channel where randomized welcome messages are sent in this guild; otherwise null if none is + /// set. + /// public SocketTextChannel SystemChannel { get @@ -140,6 +151,9 @@ namespace Discord.WebSocket /// /// Gets a collection of text channels present in this guild. /// + /// + /// A collection of text channels in this guild. + /// public IReadOnlyCollection TextChannels => Channels.Select(x => x as SocketTextChannel).Where(x => x != null).ToImmutableArray(); /// @@ -459,6 +473,7 @@ namespace Discord.WebSocket /// /// The name of the new channel. /// The options to be used when sending the request. + /// The delegate containing the properties to be applied to the channel upon its creation. /// is null. /// /// The created text channel. @@ -469,6 +484,7 @@ namespace Discord.WebSocket /// Creates a voice channel with the provided name. /// /// The name of the new 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. /// @@ -521,11 +537,11 @@ namespace Discord.WebSocket //Roles /// - /// Returns a role with the provided role ID. + /// Gets a role. /// - /// The ID of the role. + /// The snowflake identifier of the role. /// - /// The role associated with the ID. + /// The role associated with the snowflake identifier. /// public SocketRole GetRole(ulong id) { @@ -655,7 +671,7 @@ namespace Discord.WebSocket /// The ID of the webhook. /// The options to be used when sending the request. /// - /// An awaitable Task containing the webhook associated with the ID. + /// An awaitable containing the webhook associated with the ID. /// public Task GetWebhookAsync(ulong id, RequestOptions options = null) => GuildHelper.GetWebhookAsync(this, Discord, id, options); @@ -664,7 +680,7 @@ namespace Discord.WebSocket /// /// The options to be used when sending the request. /// - /// An awaitable Task containing a collection of webhooks. + /// An awaitable containing a collection of webhooks. /// public Task> GetWebhooksAsync(RequestOptions options = null) => GuildHelper.GetWebhooksAsync(this, Discord, options);