Add documentation

src/Discord.Net.Core/Entities/Activities/GameAsset.cs

@@ -12,15 +12,26 @@ namespace Discord
         /// <summary>
         ///     Gets the description of the asset.
         /// </summary>
+        /// <returns>
+        ///     A string containing the description of the asset.
+        /// </returns>
         public string Text { get; internal set; }
         /// <summary>
         ///     Gets the image ID of the asset.
         /// </summary>
+        /// <returns>
+        ///     A string containing the unique image identifier of the asset.
+        /// </returns>
         public string ImageId { get; internal set; }
 
         /// <summary>
-        ///     Returns the image URL of the asset, or <c>null</c> when the application ID does not exist.
+        ///     Returns the image URL of the asset.
         /// </summary>
+        /// <param name="size">The size of the image to return in. This can be any power of two between 16 and 2048.</param>
+        /// <param name="format">The format to return.</param>
+        /// <returns>
+        ///     A string pointing to the image URL of the asset; <c>null</c> when the application ID does not exist.
+        /// </returns>
         public string GetImageUrl(ImageFormat format = ImageFormat.Auto, ushort size = 128)
             => ApplicationId.HasValue ? CDN.GetRichAssetUrl(ApplicationId.Value, ImageId, size, format) : null;
     }

src/Discord.Net.Core/Entities/Activities/GameParty.cs

@@ -10,11 +10,17 @@ namespace Discord
         /// <summary>
         ///     Gets the ID of the party.
         /// </summary>
+        /// <returns>
+        ///     A string containing the unique identifier of the party.
+        /// </returns>
         public string Id { get; internal set; }
         public long Members { get; internal set; }
         /// <summary>
         ///     Gets the party's current and maximum size.
         /// </summary>
+        /// <returns>
+        ///     A <see cref="long"/> representing the capacity of the party.
+        /// </returns>
         public long Capacity { get; internal set; }
     }
 }

src/Discord.Net.Core/Entities/Activities/IActivity.cs

@@ -8,10 +8,16 @@ namespace Discord
         /// <summary>
         ///     Gets the name of the activity.
         /// </summary>
+        /// <returns>
+        ///     A string containing the name of the activity that the user is doing.
+        /// </returns>
         string Name { get; }
         /// <summary>
         ///     Gets the type of the activity.
         /// </summary>
+        /// <returns>
+        ///     The type of activity.
+        /// </returns>
         ActivityType Type { get; }
     }
 }

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
 {
     /// <summary>
-    /// The action type within a <see cref="IAuditLogEntry"/>
+    ///     Representing a type of action within an <see cref="IAuditLogEntry"/>.
     /// </summary>
     public enum ActionType
     {
+        /// <summary>
+        ///     this guild was updated.
+        /// </summary>
         GuildUpdated = 1,
 
+        /// <summary>
+        ///     A channel was created.
+        /// </summary>
         ChannelCreated = 10,
+        /// <summary>
+        ///     A channel was updated.
+        /// </summary>
         ChannelUpdated = 11,
+        /// <summary>
+        ///     A channel was deleted.
+        /// </summary>
         ChannelDeleted = 12,
 
+        /// <summary>
+        ///     A permission overwrite was created for a channel.
+        /// </summary>
         OverwriteCreated = 13,
+        /// <summary>
+        ///     A permission overwrite was updated for a channel.
+        /// </summary>
         OverwriteUpdated = 14,
+        /// <summary>
+        ///     A permission overwrite was deleted for a channel.
+        /// </summary>
         OverwriteDeleted = 15,
 
+        /// <summary>
+        ///     A user was kicked from this guild.
+        /// </summary>
         Kick = 20,
+        /// <summary>
+        ///     A prune took place in this guild.
+        /// </summary>
         Prune = 21,
+        /// <summary>
+        ///     A user banned another user from this guild.
+        /// </summary>
         Ban = 22,
+        /// <summary>
+        ///     A user unbanned another user from this guild.
+        /// </summary>
         Unban = 23,
 
+        /// <summary>
+        ///     A guild member whose information was updated.
+        /// </summary>
         MemberUpdated = 24,
+        /// <summary>
+        ///     A guild member's role collection was updated.
+        /// </summary>
         MemberRoleUpdated = 25,
 
+        /// <summary>
+        ///     A role was created in this guild.
+        /// </summary>
         RoleCreated = 30,
+        /// <summary>
+        ///     A role was updated in this guild.
+        /// </summary>
         RoleUpdated = 31,
+        /// <summary>
+        ///     A role was deleted from this guild.
+        /// </summary>
         RoleDeleted = 32,
 
+        /// <summary>
+        ///     An invite was created in this guild.
+        /// </summary>
         InviteCreated = 40,
+        /// <summary>
+        ///     An invite was updated in this guild.
+        /// </summary>
         InviteUpdated = 41,
+        /// <summary>
+        ///     An invite was deleted from this guild.
+        /// </summary>
         InviteDeleted = 42,
 
+        /// <summary>
+        ///     A Webhook was created in this guild.
+        /// </summary>
         WebhookCreated = 50,
+        /// <summary>
+        ///     A Webhook was updated in this guild.
+        /// </summary>
         WebhookUpdated = 51,
+        /// <summary>
+        ///     A Webhook was deleted from this guild.
+        /// </summary>
         WebhookDeleted = 52,
 
+        /// <summary>
+        ///     An emoji was created in this guild.
+        /// </summary>
         EmojiCreated = 60,
+        /// <summary>
+        ///     An emoji was updated in this guild.
+        /// </summary>
         EmojiUpdated = 61,
+        /// <summary>
+        ///     An emoji was deleted from this guild.
+        /// </summary>
         EmojiDeleted = 62,
 
+        /// <summary>
+        ///     A message was deleted from this guild.
+        /// </summary>
         MessageDeleted = 72
     }
 }

src/Discord.Net.Core/Entities/AuditLogs/IAuditLogData.cs

@@ -1,7 +1,7 @@
 namespace Discord
 {
     /// <summary>
-    /// Represents data applied to an <see cref="IAuditLogEntry"/>.
+    ///     Represents data applied to an <see cref="IAuditLogEntry" />.
     /// </summary>
     public interface IAuditLogData
     { }

src/Discord.Net.Core/Entities/Channels/IChannel.cs

@@ -11,16 +11,32 @@ namespace Discord
         /// <summary>
         ///     Gets the name of this channel.
         /// </summary>
+        /// <returns>
+        ///     A string containing the name of this channel.
+        /// </returns>
         string Name { get; }
-        
+
         /// <summary>
         ///     Gets a collection of all users in this channel.
         /// </summary>
+        /// <param name="mode">The <see cref="CacheMode"/> that determines whether the object should be fetched from cache.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A paged collection containing a collection of users that can access this channel. Flattening the
+        ///     paginated response into a collection of users with 
+        ///     <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> is required if you wish to access the users.
+        /// </returns>
         IAsyncEnumerable<IReadOnlyCollection<IUser>> GetUsersAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
-        
+
         /// <summary>
-        ///     Gets a user in this channel with the provided ID.
+        ///     Gets a user in this channel.
         /// </summary>
+        /// <param name="id">The snowflake identifier of the user (e.g. 168693960628371456).</param>
+        /// <param name="mode">The <see cref="CacheMode"/> that determines whether the object should be fetched from cache.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/> containing a user object that represents the user.
+        /// </returns>
         Task<IUser> GetUserAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
     }
 }

src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs

@@ -24,14 +24,14 @@ namespace Discord
         ///     Gets the guild associated with this channel.
         /// </summary>
         /// <returns>
-        ///     The guild that this channel belongs to.
+        ///     A guild that this channel belongs to.
         /// </returns>
         IGuild Guild { get; }
         /// <summary>
         ///     Gets the guild ID associated with this channel.
         /// </summary>
         /// <returns>
-        ///     The guild ID that this channel belongs to.
+        ///     A guild snowflake identifier for the guild that this channel belongs to.
         /// </returns>
         ulong GuildId { get; }
         /// <summary>
@@ -55,16 +55,25 @@ namespace Discord
         ///     If <c>true</c>, a user accepting this invite will be kicked from the guild after closing their client.
         /// </param>
         /// <param name="isUnique">
-        ///     If <c>true</c>, don't try to reuse a similar invite (useful for creating many unique one time use invites).
+        ///     If <c>true</c>, don't try to reuse a similar invite (useful for creating many unique one time use
+        ///     invites).
         /// </param>
         /// <param name="options">
         ///     The options to be used when sending the request.
         /// </param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/> containing an invite metadata object containing information for the
+        ///     created invite. 
+        /// </returns>
         Task<IInviteMetadata> CreateInviteAsync(int? maxAge = 86400, int? maxUses = default(int?), bool isTemporary = false, bool isUnique = false, RequestOptions options = null);
         /// <summary>
         ///     Returns a collection of all invites to this channel.
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/> containing a read-only collection of invite metadata that are created
+        ///     for this channel.
+        /// </returns>
         Task<IReadOnlyCollection<IInviteMetadata>> GetInvitesAsync(RequestOptions options = null);
 
         /// <summary>
@@ -72,29 +81,44 @@ namespace Discord
         /// </summary>
         /// <param name="func">The properties to modify the channel with.</param>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/>.
+        /// </returns>
         Task ModifyAsync(Action<GuildChannelProperties> func, RequestOptions options = null);
 
         /// <summary>
         ///     Gets the permission overwrite for a specific role, or <c>null</c> if one does not exist.
         /// </summary>
         /// <param name="role">The role to get the overwrite from.</param>
+        /// <returns>
+        ///     An overwrite object for the targeted role; <c>null</c> if none is set.
+        /// </returns>
         OverwritePermissions? GetPermissionOverwrite(IRole role);
         /// <summary>
         ///     Gets the permission overwrite for a specific user, or <c>null</c> if one does not exist.
         /// </summary>
         /// <param name="user">The user to get the overwrite from.</param>
+        /// <returns>
+        ///     An overwrite object for the targeted user; <c>null</c> if none is set.
+        /// </returns>
         OverwritePermissions? GetPermissionOverwrite(IUser user);
         /// <summary>
         ///     Removes the permission overwrite for the given role, if one exists.
         /// </summary>
         /// <param name="role">The role to remove the overwrite from.</param>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/>.
+        /// </returns>
         Task RemovePermissionOverwriteAsync(IRole role, RequestOptions options = null);
         /// <summary>
         ///     Removes the permission overwrite for the given user, if one exists.
         /// </summary>
         /// <param name="user">The user to remove the overwrite from.</param>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/>.
+        /// </returns>
         Task RemovePermissionOverwriteAsync(IUser user, RequestOptions options = null);
 
         /// <summary>
@@ -103,6 +127,9 @@ namespace Discord
         /// <param name="role">The role to add the overwrite to.</param>
         /// <param name="permissions">The overwrite to add to the role.</param>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/>.
+        /// </returns>
         Task AddPermissionOverwriteAsync(IRole role, OverwritePermissions permissions, RequestOptions options = null);
         /// <summary>
         ///     Adds or updates the permission overwrite for the given user.
@@ -110,6 +137,9 @@ namespace Discord
         /// <param name="user">The user to add the overwrite to.</param>
         /// <param name="permissions">The overwrite to add to the user.</param>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/>.
+        /// </returns>
         Task AddPermissionOverwriteAsync(IUser user, OverwritePermissions permissions, RequestOptions options = null);
 
         /// <summary>
@@ -119,6 +149,11 @@ namespace Discord
         /// The <see cref="CacheMode" /> that determines whether the object should be fetched from cache.
         /// </param>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A paged collection containing a collection of guild users that can access this channel. Flattening the
+        ///     paginated response into a collection of users with 
+        ///     <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> is required if you wish to access the users.
+        /// </returns>
         new IAsyncEnumerable<IReadOnlyCollection<IGuildUser>> GetUsersAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
         ///     Gets a user in this channel with the provided ID.
@@ -128,6 +163,9 @@ namespace Discord
         /// The <see cref="CacheMode" /> that determines whether the object should be fetched from cache.
         /// </param>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/> containing a guild user object that represents the user.
+        /// </returns>
         new Task<IGuildUser> GetUserAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
     }
 }

src/Discord.Net.Core/Entities/Channels/INestedChannel.cs

@@ -21,7 +21,7 @@ namespace Discord
         /// <param name="mode">The <see cref="CacheMode"/> that determines whether the object should be fetched from cache.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <remarks>
-        ///     A generic category channel representing the parent of this channel; <c>null</c> if none is set.
+        ///     A category channel representing the parent of this channel; <c>null</c> if none is set.
         /// </remarks>
         Task<ICategoryChannel> GetCategoryAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
     }

src/Discord.Net.Core/Entities/Channels/ITextChannel.cs

@@ -80,7 +80,7 @@ namespace Discord
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     A collection of webhooks.
+        ///     An awaitable <see cref="Task"/> containing a collection of webhooks.
         /// </returns>
         Task<IReadOnlyCollection<IWebhook>> GetWebhooksAsync(RequestOptions options = null);
     }

src/Discord.Net.Core/Entities/Channels/ReorderChannelProperties.cs

@@ -8,10 +8,16 @@ namespace Discord
         /// <summary>
         ///     Gets the ID of the channel to apply this position to.
         /// </summary>
+        /// <returns>
+        ///     A <see cref="ulong"/> representing the snowflake identififer of this channel.
+        /// </returns>
         public ulong Id { get; }
         /// <summary>
         ///     Gets the new zero-based position of this channel.
         /// </summary>
+        /// <returns>
+        ///     An <see cref="int"/> representing the new position of this channel.
+        /// </returns>
         public int Position { get; }
 
         /// <summary> Creates a <see cref="ReorderChannelProperties"/> used to reorder a channel. </summary>

src/Discord.Net.Core/Entities/Guilds/IBan.cs

@@ -9,7 +9,7 @@ namespace Discord
         ///     Gets the banned user.
         /// </summary>
         /// <returns>
-        ///     A generic <see cref="IUser"/> object that was banned.
+        ///     A user that was banned.
         /// </returns>
         IUser User { get; }
         /// <summary>

src/Discord.Net.Core/Entities/Invites/IInvite.cs

@@ -46,7 +46,7 @@ namespace Discord
         ///     Gets the guild this invite is linked to.
         /// </summary>
         /// <returns>
-        ///     A generic <see cref="IGuild"/> representing the guild that the invite points to.
+        ///     A guild object representing the guild that the invite points to.
         /// </returns>
         IGuild Guild { get; }
         /// <summary>

src/Discord.Net.Core/Entities/Invites/IInviteMetadata.cs

@@ -11,7 +11,7 @@ namespace Discord
         ///     Gets the user that created this invite.
         /// </summary>
         /// <returns>
-        ///     A generic <see cref="IUser"/> that created this invite.
+        ///     A user that created this invite.
         /// </returns>
         IUser Inviter { get; }
         /// <summary>

src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/BanAuditLogData.cs

@@ -25,7 +25,7 @@ namespace Discord.Rest
         ///     Gets the user that was banned.
         /// </summary>
         /// <returns>
-        ///     A generic <see cref="IUser"/> object representing the banned user.
+        ///     A user object representing the banned user.
         /// </returns>
         public IUser Target { get; }
     }

src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/GuildInfo.cs

@@ -71,7 +71,7 @@ namespace Discord.Rest
         ///     Gets the owner of this guild.
         /// </summary>
         /// <returns>
-        ///     A generic <see cref="IUser"/> object representing the owner of this guild.
+        ///     A user object representing the owner of this guild.
         /// </returns>
         public IUser Owner { get; }
         /// <summary>

src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteCreateAuditLogData.cs

@@ -74,7 +74,7 @@ namespace Discord.Rest
         ///     Gets the user that created this invite.
         /// </summary>
         /// <returns>
-        ///     A generic <see cref="IUser"/> that created this invite.
+        ///     A user that created this invite.
         /// </returns>
         public IUser Creator { get; }
         /// <summary>

src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteDeleteAuditLogData.cs

@@ -74,7 +74,7 @@ namespace Discord.Rest
         ///     Gets the user that created this invite.
         /// </summary>
         /// <returns>
-        ///     A generic <see cref="IUser"/> that created this invite.
+        ///     A user that created this invite.
         /// </returns>
         public IUser Creator { get; }
         /// <summary>

src/Discord.Net.WebSocket/BaseSocketClient.cs

@@ -76,7 +76,7 @@ namespace Discord.WebSocket
         ///     </note>
         /// </remarks>
         /// <returns>
-        ///     A WebSocket-based generic user; <c>null</c> when the user cannot be found.
+        ///     A generic WebSocket-based user; <c>null</c> when the user cannot be found.
         /// </returns>
         public abstract SocketUser GetUser(ulong id);
 
@@ -98,7 +98,7 @@ namespace Discord.WebSocket
         ///     </note>
         /// </remarks>
         /// <returns>
-        ///     A WebSocket-based generic user; <c>null</c> when the user cannot be found.
+        ///     A generic WebSocket-based user; <c>null</c> when the user cannot be found.
         /// </returns>
         public abstract SocketUser GetUser(string username, string discriminator);
         /// <summary>