Add partial documentation for audit log objects

Still34 · May 26, 2018 · cb57ada · cb57ada
1 parent afda0cd
commit cb57ada
Show file tree

Hide file tree

Showing 21 changed files with 186 additions and 47 deletions.
diff --git a/src/Discord.Net.Core/Entities/AuditLogs/IAuditLogEntry.cs b/src/Discord.Net.Core/Entities/AuditLogs/IAuditLogEntry.cs
@@ -1,7 +1,7 @@
 namespace Discord
 {
     /// <summary>
-    /// Represents an entry in an audit log.
+    ///     Represents a generic audit log entry.
     /// </summary>
     public interface IAuditLogEntry : IEntity<ulong>
     {

diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/BanAuditLogData.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/BanAuditLogData.cs
@@ -6,7 +6,7 @@
 namespace Discord.Rest
 {
     /// <summary>
-    /// Represents an audit log data for a ban action.
+    ///     Represents a piece of audit log data related to a ban.
     /// </summary>
     public class BanAuditLogData : IAuditLogData
     {
@@ -24,6 +24,9 @@ internal static BanAuditLogData Create(BaseDiscordClient discord, Model log, Ent
         /// <summary>
         ///     Gets the user that was banned.
         /// </summary>
+        /// <returns>
+        ///     A generic <see cref="IUser"/> object representing the banned user.
+        /// </returns>
         public IUser Target { get; }
     }
 }
diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelCreateAuditLogData.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelCreateAuditLogData.cs
@@ -7,7 +7,7 @@
 namespace Discord.Rest
 {
     /// <summary>
-    ///     Represents an audit log data for a channel creation.
+    ///     Represents a piece of audit log data related to a channel creation.
     /// </summary>
     public class ChannelCreateAuditLogData : IAuditLogData
     {

diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelDeleteAuditLogData.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelDeleteAuditLogData.cs
@@ -7,7 +7,7 @@
 namespace Discord.Rest
 {
     /// <summary>
-    ///     Represents an audit log data for a channel deletion.
+    ///     Represents a piece of audit log data related to a channel deletion.
     /// </summary>
     public class ChannelDeleteAuditLogData : IAuditLogData
     {

diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelInfo.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelInfo.cs
@@ -1,7 +1,7 @@
 namespace Discord.Rest
 {
     /// <summary>
-    /// Represents information for a channel.
+    ///     Represents information for a channel.
     /// </summary>
     public struct ChannelInfo
     {

diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelUpdateAuditLogData.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelUpdateAuditLogData.cs
@@ -6,7 +6,7 @@
 namespace Discord.Rest
 {
     /// <summary>
-    ///     Represents an audit log data for a channel update.
+    ///     Represents a piece of audit log data related to a channel update.
     /// </summary>
     public class ChannelUpdateAuditLogData : IAuditLogData
     {

diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/EmoteCreateAuditLogData.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/EmoteCreateAuditLogData.cs
@@ -6,7 +6,7 @@
 namespace Discord.Rest
 {
     /// <summary>
-    ///     Represents an audit log data for an emoji creation.
+    ///     Represents a piece of audit log data related to an emoji creation.
     /// </summary>
     public class EmoteCreateAuditLogData : IAuditLogData
     {

diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/EmoteDeleteAuditLogData.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/EmoteDeleteAuditLogData.cs
@@ -6,7 +6,7 @@
 namespace Discord.Rest
 {
     /// <summary>
-    ///     Represents an audit log data for an emoji deletion.
+    ///     Represents a piece of audit log data related to an emoji deletion.
     /// </summary>
     public class EmoteDeleteAuditLogData : IAuditLogData
     {

diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/EmoteUpdateAuditLogData.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/EmoteUpdateAuditLogData.cs
@@ -6,7 +6,7 @@
 namespace Discord.Rest
 {
     /// <summary>
-    ///     Represents an audit log data for an emoji update.
+    ///     Represents a piece of audit log data related to an emoji update.
     /// </summary>
     public class EmoteUpdateAuditLogData : IAuditLogData
     {

diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/GuildInfo.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/GuildInfo.cs
@@ -57,7 +57,7 @@ internal GuildInfo(int? afkTimeout, DefaultMessageNotifications? defaultNotifs,
         ///     Gets the ID of this guild's icon.
         /// </summary>
         /// <returns>
-        ///     An identifier for the splash image; <c>null</c> if none is set.
+        ///     A string containing the identifier for the splash image; <c>null</c> if none is set.
         /// </returns>
         public string IconHash { get; }
         /// <summary>
@@ -71,7 +71,7 @@ internal GuildInfo(int? afkTimeout, DefaultMessageNotifications? defaultNotifs,
         ///     Gets the owner of this guild.
         /// </summary>
         /// <returns>
-        ///     An <see cref="IUser"/> object representing the owner of this guild.
+        ///     A generic <see cref="IUser"/> object representing the owner of this guild.
         /// </returns>
         public IUser Owner { get; }
         /// <summary>

diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/GuildUpdateAuditLogData.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/GuildUpdateAuditLogData.cs
@@ -1,10 +1,13 @@
-using System.Linq;
+using System.Linq;
 
 using Model = Discord.API.AuditLog;
 using EntryModel = Discord.API.AuditLogEntry;
 
 namespace Discord.Rest
 {
+    /// <summary>
+    ///     Represents a piece of audit log data related to a guild update.
+    /// </summary>
     public class GuildUpdateAuditLogData : IAuditLogData
     {
         private GuildUpdateAuditLogData(GuildInfo before, GuildInfo after)
@@ -73,7 +76,19 @@ internal static GuildUpdateAuditLogData Create(BaseDiscordClient discord, Model
             return new GuildUpdateAuditLogData(before, after);
         }
 
+        /// <summary>
+        ///     Gets the guild information before the changes.
+        /// </summary>
+        /// <returns>
+        ///     An information object containing the original guild information before the changes were made.
+        /// </returns>
         public GuildInfo Before { get; }
+        /// <summary>
+        ///     Gets the guild information after the changes.
+        /// </summary>
+        /// <returns>
+        ///     An information object containing the guild information after the changes were made.
+        /// </returns>
         public GuildInfo After { get; }
     }
 }
diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteCreateAuditLogData.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteCreateAuditLogData.cs
@@ -1,10 +1,13 @@
-using System.Linq;
+using System.Linq;
 
 using Model = Discord.API.AuditLog;
 using EntryModel = Discord.API.AuditLogEntry;
 
 namespace Discord.Rest
 {
+    /// <summary>
+    ///     Represents a piece of audit log data related to an invite creation.
+    /// </summary>
     public class InviteCreateAuditLogData : IAuditLogData
     {
         private InviteCreateAuditLogData(int maxAge, string code, bool temporary, IUser inviter, ulong channelId, int uses, int maxUses)
@@ -44,12 +47,57 @@ internal static InviteCreateAuditLogData Create(BaseDiscordClient discord, Model
             return new InviteCreateAuditLogData(maxAge, code, temporary, inviter, channelId, uses, maxUses);
         }
 
+        /// <summary>
+        ///     Gets the time (in seconds) until the invite expires.
+        /// </summary>
+        /// <returns>
+        ///     An <see cref="int"/> representing the time in seconds until this invite expires.
+        /// </returns>
         public int MaxAge { get; }
+        /// <summary>
+        ///     Gets the unique identifier for this invite.
+        /// </summary>
+        /// <returns>
+        ///     A string containing the invite code (e.g. <c>FTqNnyS</c>).
+        /// </returns>
         public string Code { get; }
+        /// <summary>
+        ///     Determines whether the invite is a temporary one (i.e. whether the invite will be removed from the guild
+        ///     when the user logs off).
+        /// </summary>
+        /// <returns>
+        ///     <c>true</c> if users accepting this invite will be removed from the guild when they log off; otherwise 
+        ///     <c>false</c>.
+        /// </returns>
         public bool Temporary { get; }
+        /// <summary>
+        ///     Gets the user that created this invite.
+        /// </summary>
+        /// <returns>
+        ///     A generic <see cref="IUser"/> that created this invite.
+        /// </returns>
         public IUser Creator { get; }
+        /// <summary>
+        ///     Gets the ID of the channel this invite is linked to.
+        /// </summary>
+        /// <returns>
+        ///     An <see cref="ulong"/> representing the channel snowflake identifier that the invite points to.
+        /// </returns>
         public ulong ChannelId { get; }
+        /// <summary>
+        ///     Gets the number of times this invite has been used.
+        /// </summary>
+        /// <returns>
+        ///     An <see cref="int"/> representing the number of times this invite has been used.
+        /// </returns>
         public int Uses { get; }
+        /// <summary>
+        ///     Gets the max number of uses this invite may have.
+        /// </summary>
+        /// <returns>
+        ///     An <see cref="int"/> representing the number of uses this invite may be accepted until it is removed
+        ///     from the guild; <c>null</c> if none is set.
+        /// </returns>
         public int MaxUses { get; }
     }
 }
diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteDeleteAuditLogData.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteDeleteAuditLogData.cs
@@ -1,10 +1,13 @@
-using System.Linq;
+using System.Linq;
 
 using Model = Discord.API.AuditLog;
 using EntryModel = Discord.API.AuditLogEntry;
 
 namespace Discord.Rest
 {
+    /// <summary>
+    ///     Represents a piece of audit log data related to an invite removal.
+    /// </summary>
     public class InviteDeleteAuditLogData : IAuditLogData
     {
         private InviteDeleteAuditLogData(int maxAge, string code, bool temporary, IUser inviter, ulong channelId, int uses, int maxUses)
@@ -44,12 +47,57 @@ internal static InviteDeleteAuditLogData Create(BaseDiscordClient discord, Model
             return new InviteDeleteAuditLogData(maxAge, code, temporary, inviter, channelId, uses, maxUses);
         }
 
+        /// <summary>
+        ///     Gets the time (in seconds) until the invite expires.
+        /// </summary>
+        /// <returns>
+        ///     An <see cref="int"/> representing the time in seconds until this invite expires.
+        /// </returns>
         public int MaxAge { get; }
+        /// <summary>
+        ///     Gets the unique identifier for this invite.
+        /// </summary>
+        /// <returns>
+        ///     A string containing the invite code (e.g. <c>FTqNnyS</c>).
+        /// </returns>
         public string Code { get; }
+        /// <summary>
+        ///     Determines whether the invite is a temporary one (i.e. whether the invite will be removed from the guild
+        ///     when the user logs off).
+        /// </summary>
+        /// <returns>
+        ///     <c>true</c> if users accepting this invite will be removed from the guild when they log off; otherwise 
+        ///     <c>false</c>.
+        /// </returns>
         public bool Temporary { get; }
+        /// <summary>
+        ///     Gets the user that created this invite.
+        /// </summary>
+        /// <returns>
+        ///     A generic <see cref="IUser"/> that created this invite.
+        /// </returns>
         public IUser Creator { get; }
+        /// <summary>
+        ///     Gets the ID of the channel this invite is linked to.
+        /// </summary>
+        /// <returns>
+        ///     An <see cref="ulong"/> representing the channel snowflake identifier that the invite points to.
+        /// </returns>
         public ulong ChannelId { get; }
+        /// <summary>
+        ///     Gets the number of times this invite has been used.
+        /// </summary>
+        /// <returns>
+        ///     An <see cref="int"/> representing the number of times this invite has been used.
+        /// </returns>
         public int Uses { get; }
+        /// <summary>
+        ///     Gets the max number of uses this invite may have.
+        /// </summary>
+        /// <returns>
+        ///     An <see cref="int"/> representing the number of uses this invite may be accepted until it is removed
+        ///     from the guild; <c>null</c> if none is set.
+        /// </returns>
         public int MaxUses { get; }
     }
 }
diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteInfo.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteInfo.cs
@@ -1,5 +1,8 @@
 namespace Discord.Rest
 {
+    /// <summary>
+    ///     Represents information for an invite.
+    /// </summary>
     public struct InviteInfo
     {
         internal InviteInfo(int? maxAge, string code, bool? temporary, ulong? channelId, int? maxUses)
@@ -11,10 +14,45 @@ internal InviteInfo(int? maxAge, string code, bool? temporary, ulong? channelId,
             MaxUses = maxUses;
         }
 
+        /// <summary>
+        ///     Gets the time (in seconds) until the invite expires.
+        /// </summary>
+        /// <returns>
+        ///     An <see cref="int"/> representing the time in seconds until this invite expires; <c>null</c> if this
+        ///     invite never expires or not specified.
+        /// </returns>
         public int? MaxAge { get; }
+        /// <summary>
+        ///     Gets the unique identifier for this invite.
+        /// </summary>
+        /// <returns>
+        ///     A string containing the invite code (e.g. <c>FTqNnyS</c>).
+        /// </returns>
         public string Code { get; }
+        /// <summary>
+        ///     Determines whether the invite is a temporary one (i.e. whether the invite will be removed from the guild
+        ///     when the user logs off).
+        /// </summary>
+        /// <returns>
+        ///     <c>true</c> if users accepting this invite will be removed from the guild when they log off, 
+        ///     <c>false</c> if not; <c>null</c> if not specified.
+        /// </returns>
         public bool? Temporary { get; }
+        /// <summary>
+        ///     Gets the ID of the channel this invite is linked to.
+        /// </summary>
+        /// <returns>
+        ///     An <see cref="ulong"/> representing the channel snowflake identifier that the invite points to; 
+        ///     <c>null</c> if not specified.
+        /// </returns>
         public ulong? ChannelId { get; }
+        /// <summary>
+        ///     Gets the max number of uses this invite may have.
+        /// </summary>
+        /// <returns>
+        ///     An <see cref="int"/> representing the number of uses this invite may be accepted until it is removed
+        ///     from the guild; <c>null</c> if none is specified.
+        /// </returns>
         public int? MaxUses { get; }
     }
 }
diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/MemberRoleAuditLogData.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/MemberRoleAuditLogData.cs
@@ -1,4 +1,3 @@
-using System;
 using System.Collections.Generic;
 using System.Linq;
 

diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/MemberUpdateAuditLogData.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/MemberUpdateAuditLogData.cs
@@ -1,8 +1,7 @@
-using System.Linq;
+using System.Linq;
 
 using Model = Discord.API.AuditLog;
 using EntryModel = Discord.API.AuditLogEntry;
-using ChangeModel = Discord.API.AuditLogChange;
 
 namespace Discord.Rest
 {

diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/OverwriteDeleteAuditLogData.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/OverwriteDeleteAuditLogData.cs
@@ -1,13 +1,7 @@
-using System;
-using System.Collections.Generic;
 using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
 
 using Model = Discord.API.AuditLog;
 using EntryModel = Discord.API.AuditLogEntry;
-using ChangeModel = Discord.API.AuditLogChange;
-using OptionModel = Discord.API.AuditLogOptions;
 
 namespace Discord.Rest
 {