From 341b9588d608bcd7460e751b7b0d2cd83bc42e32 Mon Sep 17 00:00:00 2001 From: Still Hsu <341464@gmail.com> Date: Sun, 27 May 2018 19:01:04 +0800 Subject: [PATCH] Add documentation --- .../Entities/Activities/GameAsset.cs | 13 ++- .../Entities/Activities/GameParty.cs | 6 ++ .../Entities/Activities/IActivity.cs | 6 ++ .../Entities/AuditLogs/ActionType.cs | 86 +++++++++++++++++-- .../Entities/AuditLogs/IAuditLogData.cs | 2 +- .../Entities/Channels/IChannel.cs | 22 ++++- .../Entities/Channels/IGuildChannel.cs | 44 +++++++++- .../Entities/Channels/INestedChannel.cs | 2 +- .../Entities/Channels/ITextChannel.cs | 2 +- .../Channels/ReorderChannelProperties.cs | 6 ++ src/Discord.Net.Core/Entities/Guilds/IBan.cs | 2 +- .../Entities/Invites/IInvite.cs | 2 +- .../Entities/Invites/IInviteMetadata.cs | 2 +- .../AuditLogs/DataTypes/BanAuditLogData.cs | 2 +- .../Entities/AuditLogs/DataTypes/GuildInfo.cs | 2 +- .../DataTypes/InviteCreateAuditLogData.cs | 2 +- .../DataTypes/InviteDeleteAuditLogData.cs | 2 +- src/Discord.Net.WebSocket/BaseSocketClient.cs | 4 +- 18 files changed, 181 insertions(+), 26 deletions(-) diff --git a/src/Discord.Net.Core/Entities/Activities/GameAsset.cs b/src/Discord.Net.Core/Entities/Activities/GameAsset.cs index 467b2885f..7217bded3 100644 --- a/src/Discord.Net.Core/Entities/Activities/GameAsset.cs +++ b/src/Discord.Net.Core/Entities/Activities/GameAsset.cs @@ -12,15 +12,26 @@ namespace Discord /// /// Gets the description of the asset. /// + /// + /// A string containing the description of the asset. + /// public string Text { get; internal set; } /// /// Gets the image ID of the asset. /// + /// + /// A string containing the unique image identifier of the asset. + /// public string ImageId { get; internal set; } /// - /// Returns the image URL of the asset, or null when the application ID does not exist. + /// Returns the image URL of the asset. /// + /// The size of the image to return in. This can be any power of two between 16 and 2048. + /// The format to return. + /// + /// A string pointing to the image URL of the asset; null when the application ID does not exist. + /// public string GetImageUrl(ImageFormat format = ImageFormat.Auto, ushort size = 128) => ApplicationId.HasValue ? CDN.GetRichAssetUrl(ApplicationId.Value, ImageId, size, format) : null; } diff --git a/src/Discord.Net.Core/Entities/Activities/GameParty.cs b/src/Discord.Net.Core/Entities/Activities/GameParty.cs index c3449df36..0cfa9980d 100644 --- a/src/Discord.Net.Core/Entities/Activities/GameParty.cs +++ b/src/Discord.Net.Core/Entities/Activities/GameParty.cs @@ -10,11 +10,17 @@ namespace Discord /// /// Gets the ID of the party. /// + /// + /// A string containing the unique identifier of the party. + /// public string Id { get; internal set; } public long Members { get; internal set; } /// /// Gets the party's current and maximum size. /// + /// + /// A representing the capacity of the party. + /// public long Capacity { get; internal set; } } } diff --git a/src/Discord.Net.Core/Entities/Activities/IActivity.cs b/src/Discord.Net.Core/Entities/Activities/IActivity.cs index 30d936952..ac0c1b5d7 100644 --- a/src/Discord.Net.Core/Entities/Activities/IActivity.cs +++ b/src/Discord.Net.Core/Entities/Activities/IActivity.cs @@ -8,10 +8,16 @@ namespace Discord /// /// Gets the name of the activity. /// + /// + /// A string containing the name of the activity that the user is doing. + /// string Name { get; } /// /// Gets the type of the activity. /// + /// + /// The type of activity. + /// ActivityType Type { get; } } } diff --git a/src/Discord.Net.Core/Entities/AuditLogs/ActionType.cs b/src/Discord.Net.Core/Entities/AuditLogs/ActionType.cs index e5a4ff30a..2561a0970 100644 --- a/src/Discord.Net.Core/Entities/AuditLogs/ActionType.cs +++ b/src/Discord.Net.Core/Entities/AuditLogs/ActionType.cs @@ -1,50 +1,122 @@ -using System; -using System.Collections.Generic; -using System.Linq; -using System.Text; -using System.Threading.Tasks; - namespace Discord { /// - /// The action type within a + /// Representing a type of action within an . /// public enum ActionType { + /// + /// this guild was updated. + /// GuildUpdated = 1, + /// + /// A channel was created. + /// ChannelCreated = 10, + /// + /// A channel was updated. + /// ChannelUpdated = 11, + /// + /// A channel was deleted. + /// ChannelDeleted = 12, + /// + /// A permission overwrite was created for a channel. + /// OverwriteCreated = 13, + /// + /// A permission overwrite was updated for a channel. + /// OverwriteUpdated = 14, + /// + /// A permission overwrite was deleted for a channel. + /// OverwriteDeleted = 15, + /// + /// A user was kicked from this guild. + /// Kick = 20, + /// + /// A prune took place in this guild. + /// Prune = 21, + /// + /// A user banned another user from this guild. + /// Ban = 22, + /// + /// A user unbanned another user from this guild. + /// Unban = 23, + /// + /// A guild member whose information was updated. + /// MemberUpdated = 24, + /// + /// A guild member's role collection was updated. + /// MemberRoleUpdated = 25, + /// + /// A role was created in this guild. + /// RoleCreated = 30, + /// + /// A role was updated in this guild. + /// RoleUpdated = 31, + /// + /// A role was deleted from this guild. + /// RoleDeleted = 32, + /// + /// An invite was created in this guild. + /// InviteCreated = 40, + /// + /// An invite was updated in this guild. + /// InviteUpdated = 41, + /// + /// An invite was deleted from this guild. + /// InviteDeleted = 42, + /// + /// A Webhook was created in this guild. + /// WebhookCreated = 50, + /// + /// A Webhook was updated in this guild. + /// WebhookUpdated = 51, + /// + /// A Webhook was deleted from this guild. + /// WebhookDeleted = 52, + /// + /// An emoji was created in this guild. + /// EmojiCreated = 60, + /// + /// An emoji was updated in this guild. + /// EmojiUpdated = 61, + /// + /// An emoji was deleted from this guild. + /// EmojiDeleted = 62, + /// + /// A message was deleted from this guild. + /// MessageDeleted = 72 } } diff --git a/src/Discord.Net.Core/Entities/AuditLogs/IAuditLogData.cs b/src/Discord.Net.Core/Entities/AuditLogs/IAuditLogData.cs index da28b53a5..5d87c9d58 100644 --- a/src/Discord.Net.Core/Entities/AuditLogs/IAuditLogData.cs +++ b/src/Discord.Net.Core/Entities/AuditLogs/IAuditLogData.cs @@ -1,7 +1,7 @@ namespace Discord { /// - /// Represents data applied to an . + /// Represents data applied to an . /// public interface IAuditLogData { } diff --git a/src/Discord.Net.Core/Entities/Channels/IChannel.cs b/src/Discord.Net.Core/Entities/Channels/IChannel.cs index 4f14431c5..04408989b 100644 --- a/src/Discord.Net.Core/Entities/Channels/IChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IChannel.cs @@ -11,16 +11,32 @@ namespace Discord /// /// Gets the name of this channel. /// + /// + /// A string containing the name of this channel. + /// string Name { get; } - + /// /// Gets a collection of all users in this channel. /// + /// The that determines whether the object should be fetched from cache. + /// The options to be used when sending the request. + /// + /// A paged collection containing a collection of users that can access this channel. Flattening the + /// paginated response into a collection of users with + /// is required if you wish to access the users. + /// IAsyncEnumerable> GetUsersAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); - + /// - /// Gets a user in this channel with the provided ID. + /// 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 options to be used when sending the request. + /// + /// An awaitable containing a user object that represents the user. + /// Task GetUserAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); } } diff --git a/src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs b/src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs index 0c8ae3b58..301737aa1 100644 --- a/src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs @@ -24,14 +24,14 @@ namespace Discord /// Gets the guild associated with this channel. /// /// - /// The guild that this channel belongs to. + /// A guild that this channel belongs to. /// IGuild Guild { get; } /// /// Gets the guild ID associated with this channel. /// /// - /// The guild ID that this channel belongs to. + /// A guild snowflake identifier for the guild that this channel belongs to. /// ulong GuildId { get; } /// @@ -55,16 +55,25 @@ namespace Discord /// 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). + /// 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. + /// Task CreateInviteAsync(int? maxAge = 86400, int? maxUses = default(int?), bool isTemporary = false, bool isUnique = false, RequestOptions options = null); /// /// Returns a collection of all invites to this channel. /// /// 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. + /// Task> GetInvitesAsync(RequestOptions options = null); /// @@ -72,29 +81,44 @@ namespace Discord /// /// The properties to modify the channel with. /// The options to be used when sending the request. + /// + /// An awaitable . + /// Task ModifyAsync(Action func, RequestOptions options = null); /// /// Gets the permission overwrite for a specific role, or null if one does not exist. /// /// The role to get the overwrite from. + /// + /// An overwrite object for the targeted role; null if none is set. + /// OverwritePermissions? GetPermissionOverwrite(IRole role); /// /// Gets the permission overwrite for a specific user, or null if one does not exist. /// /// The user to get the overwrite from. + /// + /// An overwrite object for the targeted user; null if none is set. + /// OverwritePermissions? GetPermissionOverwrite(IUser user); /// /// Removes the permission overwrite for the given role, if one exists. /// /// The role to remove the overwrite from. /// The options to be used when sending the request. + /// + /// An awaitable . + /// Task RemovePermissionOverwriteAsync(IRole role, RequestOptions options = null); /// /// Removes the permission overwrite for the given user, if one exists. /// /// The user to remove the overwrite from. /// The options to be used when sending the request. + /// + /// An awaitable . + /// Task RemovePermissionOverwriteAsync(IUser user, RequestOptions options = null); /// @@ -103,6 +127,9 @@ namespace Discord /// The role to add the overwrite to. /// The overwrite to add to the role. /// The options to be used when sending the request. + /// + /// An awaitable . + /// Task AddPermissionOverwriteAsync(IRole role, OverwritePermissions permissions, RequestOptions options = null); /// /// Adds or updates the permission overwrite for the given user. @@ -110,6 +137,9 @@ namespace Discord /// The user to add the overwrite to. /// The overwrite to add to the user. /// The options to be used when sending the request. + /// + /// An awaitable . + /// Task AddPermissionOverwriteAsync(IUser user, OverwritePermissions permissions, RequestOptions options = null); /// @@ -119,6 +149,11 @@ namespace Discord /// The that determines whether the object should be fetched from cache. /// /// The options to be used when sending the request. + /// + /// A paged collection containing a collection of guild users that can access this channel. Flattening the + /// paginated response into a collection of users with + /// is required if you wish to access the users. + /// new IAsyncEnumerable> GetUsersAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// /// Gets a user in this channel with the provided ID. @@ -128,6 +163,9 @@ 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 guild user object that represents the user. + /// new Task GetUserAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); } } diff --git a/src/Discord.Net.Core/Entities/Channels/INestedChannel.cs b/src/Discord.Net.Core/Entities/Channels/INestedChannel.cs index 9c66fb06c..62984c2a0 100644 --- a/src/Discord.Net.Core/Entities/Channels/INestedChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/INestedChannel.cs @@ -21,7 +21,7 @@ namespace Discord /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// A generic category channel representing the parent of this channel; null if none is set. + /// A 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/ITextChannel.cs b/src/Discord.Net.Core/Entities/Channels/ITextChannel.cs index 92f5b140a..a2dce09ec 100644 --- a/src/Discord.Net.Core/Entities/Channels/ITextChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/ITextChannel.cs @@ -80,7 +80,7 @@ namespace Discord /// /// The options to be used when sending the request. /// - /// A collection of webhooks. + /// An awaitable containing a collection of webhooks. /// Task> GetWebhooksAsync(RequestOptions options = null); } diff --git a/src/Discord.Net.Core/Entities/Channels/ReorderChannelProperties.cs b/src/Discord.Net.Core/Entities/Channels/ReorderChannelProperties.cs index 255279fa8..f114e0ef5 100644 --- a/src/Discord.Net.Core/Entities/Channels/ReorderChannelProperties.cs +++ b/src/Discord.Net.Core/Entities/Channels/ReorderChannelProperties.cs @@ -8,10 +8,16 @@ namespace Discord /// /// Gets the ID of the channel to apply this position to. /// + /// + /// A representing the snowflake identififer of this channel. + /// public ulong Id { get; } /// /// Gets the new zero-based position of this channel. /// + /// + /// An representing the new position of this channel. + /// public int Position { get; } /// Creates a used to reorder a channel. diff --git a/src/Discord.Net.Core/Entities/Guilds/IBan.cs b/src/Discord.Net.Core/Entities/Guilds/IBan.cs index 103cfcfd9..617f2fe04 100644 --- a/src/Discord.Net.Core/Entities/Guilds/IBan.cs +++ b/src/Discord.Net.Core/Entities/Guilds/IBan.cs @@ -9,7 +9,7 @@ namespace Discord /// Gets the banned user. /// /// - /// A generic object that was banned. + /// A user that was banned. /// IUser User { get; } /// diff --git a/src/Discord.Net.Core/Entities/Invites/IInvite.cs b/src/Discord.Net.Core/Entities/Invites/IInvite.cs index 0902d437c..90dde7474 100644 --- a/src/Discord.Net.Core/Entities/Invites/IInvite.cs +++ b/src/Discord.Net.Core/Entities/Invites/IInvite.cs @@ -46,7 +46,7 @@ namespace Discord /// Gets the guild this invite is linked to. /// /// - /// A generic representing the guild that the invite points to. + /// A guild object representing the guild that the invite points to. /// IGuild Guild { get; } /// diff --git a/src/Discord.Net.Core/Entities/Invites/IInviteMetadata.cs b/src/Discord.Net.Core/Entities/Invites/IInviteMetadata.cs index c3c4c857d..20f13a74c 100644 --- a/src/Discord.Net.Core/Entities/Invites/IInviteMetadata.cs +++ b/src/Discord.Net.Core/Entities/Invites/IInviteMetadata.cs @@ -11,7 +11,7 @@ namespace Discord /// Gets the user that created this invite. /// /// - /// A generic that created this invite. + /// A user that created this invite. /// IUser Inviter { get; } /// diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/BanAuditLogData.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/BanAuditLogData.cs index 51a859376..2e5331d59 100644 --- a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/BanAuditLogData.cs +++ b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/BanAuditLogData.cs @@ -25,7 +25,7 @@ namespace Discord.Rest /// Gets the user that was banned. /// /// - /// A generic object representing the banned user. + /// A user object representing the banned user. /// public IUser Target { get; } } diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/GuildInfo.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/GuildInfo.cs index 057930c82..494aac133 100644 --- a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/GuildInfo.cs +++ b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/GuildInfo.cs @@ -71,7 +71,7 @@ namespace Discord.Rest /// Gets the owner of this guild. /// /// - /// A generic object representing the owner of this guild. + /// A user object representing the owner of this guild. /// public IUser Owner { get; } /// diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteCreateAuditLogData.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteCreateAuditLogData.cs index c072686f5..df95d13b6 100644 --- a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteCreateAuditLogData.cs +++ b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteCreateAuditLogData.cs @@ -74,7 +74,7 @@ namespace Discord.Rest /// Gets the user that created this invite. /// /// - /// A generic that created this invite. + /// A user that created this invite. /// public IUser Creator { get; } /// diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteDeleteAuditLogData.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteDeleteAuditLogData.cs index ef5a26c11..472f227c0 100644 --- a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteDeleteAuditLogData.cs +++ b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteDeleteAuditLogData.cs @@ -74,7 +74,7 @@ namespace Discord.Rest /// Gets the user that created this invite. /// /// - /// A generic that created this invite. + /// A user that created this invite. /// public IUser Creator { get; } /// diff --git a/src/Discord.Net.WebSocket/BaseSocketClient.cs b/src/Discord.Net.WebSocket/BaseSocketClient.cs index 858fec7fe..e9d30a30d 100644 --- a/src/Discord.Net.WebSocket/BaseSocketClient.cs +++ b/src/Discord.Net.WebSocket/BaseSocketClient.cs @@ -76,7 +76,7 @@ namespace Discord.WebSocket /// /// /// - /// A WebSocket-based generic user; null when the user cannot be found. + /// A generic WebSocket-based user; null when the user cannot be found. /// public abstract SocketUser GetUser(ulong id); @@ -98,7 +98,7 @@ namespace Discord.WebSocket /// /// /// - /// A WebSocket-based generic user; null when the user cannot be found. + /// A generic WebSocket-based user; null when the user cannot be found. /// public abstract SocketUser GetUser(string username, string discriminator); ///