Merge pull request #8 from Chris-Johnston/add-misc-missing-docs

Added some miscellaneous missing xmldocs

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

@@ -1,17 +1,40 @@
-using System;
+using System;
 
 namespace Discord
 {
     public interface IGuildIntegration
     {
+        /// <summary> Gets the integration ID. </summary>
+        /// <returns> An <see cref="ulong"/> representing the unique identifier value of this integration. </returns>
         ulong Id { get; }
+        /// <summary> Gets the integration name. </summary>
+        /// <returns> A string containing the name of this integration. </returns>
         string Name { get; }
+        /// <summary> Gets the integration type (twitch, youtube, etc). </summary>
+        /// <returns> A string containing the name of the type of integration. </returns>
         string Type { get; }
+        /// <summary> Gets if this integration is enabled or not. </summary>
+        /// <summary> A value indicating if this integration is enabled. </returns>
         bool IsEnabled { get; }
+        /// <summary> Gets if this integration is syncing or not. </summary>
+        /// <returns> A value indicating if this integration is syncing. </returns>
+        /// <remarks>
+        ///     An integration with syncing enabled will update its "subscribers" on
+        ///     an interval, while one with syncing disabled will not.
+        ///     A user must manually choose when sync the integration
+        ///     if syncing is disabled.
+        /// </remarks>
         bool IsSyncing { get; }
+        /// <summary> Gets the ID that this integration uses for "subscribers". </summary>
         ulong ExpireBehavior { get; }
+        /// <summary> Gets the grace period before expiring "subscribers". </summary>
         ulong ExpireGracePeriod { get; }
+        /// <summary> Gets when this integration was last synced. </summary>
+        /// <returns> A <see cref="DateTimeOffset"/> containing a date and time of day when the integration was last synced. </returns>
         DateTimeOffset SyncedAt { get; }
+        /// <summary>
+        ///     Gets integration account information.
+        /// </summary>
         IntegrationAccount Account { get; }
 
         IGuild Guild { get; }

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

@@ -1,11 +1,15 @@
-using System.Diagnostics;
+using System.Diagnostics;
 
 namespace Discord
 {
     [DebuggerDisplay("{DebuggerDisplay,nq}")]
     public struct IntegrationAccount
     {
+        /// <summary> Gets the ID of the account. </summary>
+        /// <returns> A <see cref="string"> unique identifier of this integration account. </returns>
         public string Id { get; }
+        /// <summary> Gets the name of the account. </summary>
+        /// <returns> A string containing the name of this integration account. </returns>
         public string Name { get; private set; }
 
         public override string ToString() => Name;

src/Discord.Net.Core/Entities/Permissions/ChannelPermission.cs

@@ -22,7 +22,7 @@ namespace Discord
         /// </summary>
         AddReactions		= 0x00_00_00_40,
         /// <summary>
-        ///     Allows for reading of message.
+        ///     Allows for reading of messages. This flag is obsolete, use <see cref = "ViewChannel" /> instead.
         /// </summary>
         [Obsolete("Use ViewChannel instead.")]
         ReadMessages		= ViewChannel,

src/Discord.Net.Core/Entities/Permissions/GuildPermission.cs

@@ -14,23 +14,43 @@ namespace Discord
         /// <summary>
         ///     Allows kicking members.
         /// </summary>
+        /// <remarks>
+        ///     This permission requires the owner account to use two-factor
+        ///     authentication when used on a guild that has server-wide 2FA enabled.
+        /// </remarks>
         KickMembers			= 0x00_00_00_02,
         /// <summary>
         ///     Allows banning members.
         /// </summary>
+        /// <remarks>
+        ///     This permission requires the owner account to use two-factor
+        ///     authentication when used on a guild that has server-wide 2FA enabled.
+        /// </remarks>
         BanMembers			= 0x00_00_00_04,
         /// <summary>
         ///     Allows all permissions and bypasses channel permission overwrites.
         /// </summary>
-        Administrator		= 0x00_00_00_08,
+        /// <remarks>
+        ///     This permission requires the owner account to use two-factor
+        ///     authentication when used on a guild that has server-wide 2FA enabled.
+        /// </remarks>
+        Administrator       = 0x00_00_00_08,
         /// <summary>
         ///     Allows management and editing of channels.
         /// </summary>
-        ManageChannels		= 0x00_00_00_10,
+        /// <remarks>
+        ///     This permission requires the owner account to use two-factor
+        ///     authentication when used on a guild that has server-wide 2FA enabled.
+        /// </remarks>
+        ManageChannels      = 0x00_00_00_10,
         /// <summary>
         ///     Allows management and editing of the guild.
         /// </summary>
-        ManageGuild			= 0x00_00_00_20,
+        /// <remarks>
+        ///     This permission requires the owner account to use two-factor
+        ///     authentication when used on a guild that has server-wide 2FA enabled.
+        /// </remarks>
+        ManageGuild         = 0x00_00_00_20,
 
         // Text
 		/// <summary>
@@ -52,7 +72,11 @@ namespace Discord
         /// <summary>
         ///     Allows for deletion of other users messages.
         /// </summary>
-        ManageMessages		= 0x00_00_20_00,
+        /// <remarks>
+        ///     This permission requires the owner account to use two-factor
+        ///     authentication when used on a guild that has server-wide 2FA enabled.
+        /// </remarks>
+        ManageMessages      = 0x00_00_20_00,
         /// <summary>
         ///     Allows links sent by users with this permission will be auto-embedded.
         /// </summary>
@@ -115,14 +139,26 @@ namespace Discord
         /// <summary>
         ///     Allows management and editing of roles.
         /// </summary>
+        /// <remarks>
+        ///     This permission requires the owner account to use two-factor
+        ///     authentication when used on a guild that has server-wide 2FA enabled.
+        /// </remarks>
         ManageRoles         = 0x10_00_00_00,
         /// <summary>
         ///     Allows management and editing of webhooks.
         /// </summary>
+        /// <remarks>
+        ///     This permission requires the owner account to use two-factor
+        ///     authentication when used on a guild that has server-wide 2FA enabled.
+        /// </remarks>
         ManageWebhooks      = 0x20_00_00_00,
         /// <summary>
         ///     Allows management and editing of emojis.
         /// </summary>
+        /// <remarks>
+        ///     This permission requires the owner account to use two-factor
+        ///     authentication when used on a guild that has server-wide 2FA enabled.
+        /// </remarks>
         ManageEmojis        = 0x40_00_00_00
     }
 }

src/Discord.Net.Core/Entities/Permissions/GuildPermissions.cs

@@ -251,8 +251,19 @@ namespace Discord
                 readMessageHistory, mentionEveryone, useExternalEmojis, connect, speak, muteMembers, deafenMembers, moveMembers,
                 useVoiceActivation, prioritySpeaker, changeNickname, manageNicknames, manageRoles, manageWebhooks, manageEmojis);
 
+        /// <summary>
+        ///     Returns a value that indicates if a specific <see cref="GuildPermission"/> is enabled
+        ///     in these permissions.
+        /// </summary>
+        /// <param name="permission">The permission value to check for.</param>
+        /// <returns><c>true</c> if the permission is enabled, <c>false</c> otherwise.</returns>
         public bool Has(GuildPermission permission) => Permissions.GetValue(RawValue, permission);
 
+        /// <summary>
+        ///     Returns a <see cref="List{T}"/> containing all of the <see cref="GuildPermission"/>
+        ///     flags that are enabled.
+        /// </summary>
+        /// <returns>A <see cref="List{T}"/> containing <see cref="GuildPermission"/> flags. Empty if none are enabled.</returns>
         public List<GuildPermission> ToList()
         {
             var perms = new List<GuildPermission>();

src/Discord.Net.Core/Entities/Permissions/OverwritePermissions.cs

@@ -193,6 +193,10 @@ namespace Discord
                 embedLinks, attachFiles, readMessageHistory, mentionEveryone, useExternalEmojis, connect, speak, muteMembers, deafenMembers, 
                 moveMembers, useVoiceActivation, manageRoles, manageWebhooks);
 
+        /// <summary>
+        ///     Creates a <see cref="List{T}"/> of all the <see cref="ChannelPermission"/> values that are allowed.
+        /// </summary>
+        /// <returns>A <see cref="List{T}"/> of all allowed <see cref="ChannelPermission"/> flags. If none, the list will be empty.</returns>
         public List<ChannelPermission> ToAllowList()
         {
             var perms = new List<ChannelPermission>();
@@ -205,6 +209,11 @@ namespace Discord
             }
             return perms;
         }
+
+        /// <summary>
+        ///     Creates a <see cref="List{T}"/> of all the <see cref="ChannelPermission"/> values that are denied.
+        /// </summary>
+        /// <returns>A <see cref="List{T}"/> of all denied <see cref="ChannelPermission"/> flags. If none, the list will be empty.</returns>
         public List<ChannelPermission> ToDenyList()
         {
             var perms = new List<ChannelPermission>();

src/Discord.Net.Core/Entities/Roles/Color.cs

@@ -75,6 +75,10 @@ namespace Discord
         public static readonly Color DarkerGrey = new Color(0x546E7A);
 
         /// <summary> Gets the encoded value for this color. </summary>
+        /// <remarks>
+        ///     This value is encoded as an unsigned integer value. The most-significant 8 bits contain the red value,
+        ///     the middle 8 bits contain the green value, and the least-significant 8 bits contain the blue value.
+        /// </remarks>
         public uint RawValue { get; }
 
         /// <summary> Gets the red component for this color. </summary>

src/Discord.Net.Core/Entities/Users/IConnection.cs

@@ -1,14 +1,27 @@
-using System.Collections.Generic;
+using System.Collections.Generic;
 
 namespace Discord
 {
     public interface IConnection
     {
+        /// <summary> Gets the ID of the connection account. </summary>
+        /// <returns> A <see cref="string"/> representing the unique identifier value of this connection. </returns>
         string Id { get; }
+        /// <summary> Gets the service of the connection (twitch, youtube). </summary>
+        /// <returns> A string containing the name of this type of connection. </returns>
         string Type { get; }
+        /// <summary> Gets the username of the connection account. </summary>
+        /// <returns> A string containing the name of this connection. </returns>
         string Name { get; }
+        /// <summary> Gets whether the connection is revoked. </summary>
+        /// <returns> A value which if true indicates that this connection has been revoked, otherwise false. </returns>
         bool IsRevoked { get; }
 
+        /// <summary> Gets a <see cref="IReadOnlyCollection{T}"/> of integration IDs. </summary>
+        /// <returns>
+        ///     An <see cref="IReadOnlyCollection{T}"/> containing <see cref="ulong"/>
+        ///     representations of unique identifier values of integrations.
+        /// </returns>
         IReadOnlyCollection<ulong> IntegrationIds { get; }
     }
 }