From 098ead93d98ea9e629f9c4d8681a38ad8c1e9a82 Mon Sep 17 00:00:00 2001
From: Still Hsu <341464@gmail.com>
Date: Sat, 26 May 2018 16:33:38 +0800
Subject: [PATCH] Add partial documentation for audit log impl
---
src/Discord.Net.Core/DiscordConfig.cs | 12 ++++
.../Entities/AuditLogs/IAuditLogData.cs | 8 +--
.../Entities/Guilds/IGuild.cs | 21 ++++++-
src/Discord.Net.Core/RequestOptions.cs | 7 ++-
.../AuditLogs/DataTypes/BanAuditLogData.cs | 8 ++-
.../DataTypes/ChannelCreateAuditLogData.cs | 28 +++++++++-
.../DataTypes/ChannelDeleteAuditLogData.cs | 30 +++++++++-
.../AuditLogs/DataTypes/ChannelInfo.cs | 29 ++++++++++
.../DataTypes/ChannelUpdateAuditLogData.cs | 11 +++-
.../DataTypes/EmoteCreateAuditLogData.cs | 19 +++++--
.../DataTypes/EmoteDeleteAuditLogData.cs | 17 +++++-
.../DataTypes/EmoteUpdateAuditLogData.cs | 23 +++++++-
.../Entities/AuditLogs/DataTypes/GuildInfo.cs | 55 +++++++++++++++++++
13 files changed, 244 insertions(+), 24 deletions(-)
diff --git a/src/Discord.Net.Core/DiscordConfig.cs b/src/Discord.Net.Core/DiscordConfig.cs
index c65810d4e1..489219161b 100644
--- a/src/Discord.Net.Core/DiscordConfig.cs
+++ b/src/Discord.Net.Core/DiscordConfig.cs
@@ -93,7 +93,19 @@ public class DiscordConfig
/// The maximum number of guilds that can be gotten per-batch.
///
public const int MaxGuildsPerBatch = 100;
+ ///
+ /// Returns the max user reactions allowed to be in a request.
+ ///
+ ///
+ /// The maximum number of user reactions that can be gotten per-batch.
+ ///
public const int MaxUserReactionsPerBatch = 100;
+ ///
+ /// Returns the max audit log entries allowed to be in a request.
+ ///
+ ///
+ /// The maximum number of audit log entries that can be gotten per-batch.
+ ///
public const int MaxAuditLogEntriesPerBatch = 100;
///
diff --git a/src/Discord.Net.Core/Entities/AuditLogs/IAuditLogData.cs b/src/Discord.Net.Core/Entities/AuditLogs/IAuditLogData.cs
index 47aaffb26b..da28b53a56 100644
--- a/src/Discord.Net.Core/Entities/AuditLogs/IAuditLogData.cs
+++ b/src/Discord.Net.Core/Entities/AuditLogs/IAuditLogData.cs
@@ -1,13 +1,7 @@
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
-
namespace Discord
{
///
- /// Represents data applied to an
+ /// Represents data applied to an .
///
public interface IAuditLogData
{ }
diff --git a/src/Discord.Net.Core/Entities/Guilds/IGuild.cs b/src/Discord.Net.Core/Entities/Guilds/IGuild.cs
index 2b18726e22..8d6c090b53 100644
--- a/src/Discord.Net.Core/Entities/Guilds/IGuild.cs
+++ b/src/Discord.Net.Core/Entities/Guilds/IGuild.cs
@@ -22,7 +22,8 @@ public interface IGuild : IDeletable, ISnowflakeEntity
/// automatically moved to the AFK voice channel.
///
///
- /// The amount of time in seconds for a user to be marked as inactive and moved into the AFK voice channel.
+ /// An representing the amount of time in seconds for a user to be marked as inactive
+ /// and moved into the AFK voice channel.
///
int AFKTimeout { get; }
///
@@ -94,8 +95,12 @@ public interface IGuild : IDeletable, ISnowflakeEntity
bool Available { get; }
///
- /// Gets the ID of the AFK voice channel for this guild, or null if none is set.
+ /// Gets the ID of the AFK voice channel for this guild.
///
+ ///
+ /// An representing the snowflake identifier of the AFK voice channel; null if
+ /// none is set.
+ ///
ulong? AFKChannelId { get; }
///
/// Gets the ID of the the default channel for this guild.
@@ -542,7 +547,17 @@ public interface IGuild : IDeletable, ISnowflakeEntity
///
Task PruneUsersAsync(int days = 30, bool simulate = false, RequestOptions options = null);
- /// Gets the specified number of audit log entries for this guild.
+ ///
+ /// Gets the specified number of audit log entries for this guild.
+ ///
+ /// The number of audit log entries to fetch.
+ ///
+ /// 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 requested audit log entries.
+ ///
Task> GetAuditLogAsync(int limit = DiscordConfig.MaxAuditLogEntriesPerBatch,
CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
diff --git a/src/Discord.Net.Core/RequestOptions.cs b/src/Discord.Net.Core/RequestOptions.cs
index c2d1f65494..785b518f3e 100644
--- a/src/Discord.Net.Core/RequestOptions.cs
+++ b/src/Discord.Net.Core/RequestOptions.cs
@@ -25,9 +25,12 @@ public class RequestOptions
public RetryMode? RetryMode { get; set; }
public bool HeaderOnly { get; internal set; }
///
- /// Gets or sets the reason for this action in the guild's audit log. Note that this property may not apply
- /// to every action.
+ /// Gets or sets the reason for this action in the guild's audit log.
///
+ ///
+ /// Gets or sets the reason that will be written to the guild's audit log if applicable. This may not apply
+ /// to all actions.
+ ///
public string AuditLogReason { get; set; }
internal bool IgnoreState { get; set; }
diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/BanAuditLogData.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/BanAuditLogData.cs
index 4b9d5875f2..b249486aa1 100644
--- a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/BanAuditLogData.cs
+++ b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/BanAuditLogData.cs
@@ -1,10 +1,13 @@
-using System.Linq;
+using System.Linq;
using Model = Discord.API.AuditLog;
using EntryModel = Discord.API.AuditLogEntry;
namespace Discord.Rest
{
+ ///
+ /// Represents an audit log data for a ban action.
+ ///
public class BanAuditLogData : IAuditLogData
{
private BanAuditLogData(IUser user)
@@ -18,6 +21,9 @@ internal static BanAuditLogData Create(BaseDiscordClient discord, Model log, Ent
return new BanAuditLogData(RestUser.Create(discord, userInfo));
}
+ ///
+ /// Gets the user that was banned.
+ ///
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
index ef4787295a..6539519a13 100644
--- a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelCreateAuditLogData.cs
+++ b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelCreateAuditLogData.cs
@@ -1,4 +1,3 @@
-using Newtonsoft.Json.Linq;
using System.Collections.Generic;
using System.Linq;
@@ -7,6 +6,9 @@
namespace Discord.Rest
{
+ ///
+ /// Represents an audit log data for a channel creation.
+ ///
public class ChannelCreateAuditLogData : IAuditLogData
{
private ChannelCreateAuditLogData(ulong id, string name, ChannelType type, IReadOnlyCollection overwrites)
@@ -44,9 +46,33 @@ internal static ChannelCreateAuditLogData Create(BaseDiscordClient discord, Mode
return new ChannelCreateAuditLogData(entry.TargetId.Value, name, type, overwrites.ToReadOnlyCollection());
}
+ ///
+ /// Gets the snowflake ID of the created channel.
+ ///
+ ///
+ /// An representing the snowflake identifier for the created channel.
+ ///
public ulong ChannelId { get; }
+ ///
+ /// Gets the name of the created channel.
+ ///
+ ///
+ /// A string containing the name of the created channel.
+ ///
public string ChannelName { get; }
+ ///
+ /// Gets the type of the created channel.
+ ///
+ ///
+ /// The type of channel that was created.
+ ///
public ChannelType ChannelType { get; }
+ ///
+ /// Gets a collection of permission overwrites that was assigned to the created channel.
+ ///
+ ///
+ /// A collection of permission .
+ ///
public IReadOnlyCollection Overwrites { get; }
}
}
diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelDeleteAuditLogData.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelDeleteAuditLogData.cs
index 4816ce770f..260de55096 100644
--- a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelDeleteAuditLogData.cs
+++ b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelDeleteAuditLogData.cs
@@ -1,14 +1,14 @@
-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;
namespace Discord.Rest
{
+ ///
+ /// Represents an audit log data for a channel deletion.
+ ///
public class ChannelDeleteAuditLogData : IAuditLogData
{
private ChannelDeleteAuditLogData(ulong id, string name, ChannelType type, IReadOnlyCollection overwrites)
@@ -37,9 +37,33 @@ internal static ChannelDeleteAuditLogData Create(BaseDiscordClient discord, Mode
return new ChannelDeleteAuditLogData(id, name, type, overwrites.ToReadOnlyCollection());
}
+ ///
+ /// Gets the snowflake ID of the deleted channel.
+ ///
+ ///
+ /// An representing the snowflake identifier for the deleted channel.
+ ///
public ulong ChannelId { get; }
+ ///
+ /// Gets the name of the deleted channel.
+ ///
+ ///
+ /// A string containing the name of the deleted channel.
+ ///
public string ChannelName { get; }
+ ///
+ /// Gets the type of the deleted channel.
+ ///
+ ///
+ /// The type of channel that was deleted.
+ ///
public ChannelType ChannelType { get; }
+ ///
+ /// Gets a collection of permission overwrites that was assigned to the deleted channel.
+ ///
+ ///
+ /// A collection of permission .
+ ///
public IReadOnlyCollection Overwrites { get; }
}
}
diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelInfo.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelInfo.cs
index e2d6064a9a..753e1d3a56 100644
--- a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelInfo.cs
+++ b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelInfo.cs
@@ -1,5 +1,8 @@
namespace Discord.Rest
{
+ ///
+ /// Represents information for a channel.
+ ///
public struct ChannelInfo
{
internal ChannelInfo(string name, string topic, int? bitrate, int? limit)
@@ -10,9 +13,35 @@ internal ChannelInfo(string name, string topic, int? bitrate, int? limit)
UserLimit = limit;
}
+ ///
+ /// Gets the name of this channel.
+ ///
+ ///
+ /// A string containing the name of this channel.
+ ///
public string Name { get; }
+ ///
+ /// Gets the topic of this channel.
+ ///
+ ///
+ /// A string containing the topic of this channel, if any.
+ ///
public string Topic { get; }
+ ///
+ /// Gets the bitrate of this channel if applicable.
+ ///
+ ///
+ /// An representing the bitrate set for the voice channel; null if not
+ /// applicable.
+ ///
public int? Bitrate { get; }
+ ///
+ /// Gets the number of users allowed to be in this channel if applicable.
+ ///
+ ///
+ /// An representing the number of users allowed to be in this voice channel;
+ /// null if not applicable.
+ ///
public int? UserLimit { get; }
}
}
diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelUpdateAuditLogData.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelUpdateAuditLogData.cs
index f3403138da..4e88a6f002 100644
--- a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelUpdateAuditLogData.cs
+++ b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelUpdateAuditLogData.cs
@@ -1,10 +1,13 @@
-using System.Linq;
+using System.Linq;
using Model = Discord.API.AuditLog;
using EntryModel = Discord.API.AuditLogEntry;
namespace Discord.Rest
{
+ ///
+ /// Represents an audit log data for a channel update.
+ ///
public class ChannelUpdateAuditLogData : IAuditLogData
{
private ChannelUpdateAuditLogData(ulong id, ChannelInfo before, ChannelInfo after)
@@ -38,6 +41,12 @@ internal static ChannelUpdateAuditLogData Create(BaseDiscordClient discord, Mode
return new ChannelUpdateAuditLogData(entry.TargetId.Value, before, after);
}
+ ///
+ /// Gets the snowflake ID of the updated channel.
+ ///
+ ///
+ /// An representing the snowflake identifier for the updated channel.
+ ///
public ulong ChannelId { get; }
public ChannelInfo Before { get; set; }
public ChannelInfo After { get; set; }
diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/EmoteCreateAuditLogData.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/EmoteCreateAuditLogData.cs
index 5d1ef8463d..1e490b42d2 100644
--- a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/EmoteCreateAuditLogData.cs
+++ b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/EmoteCreateAuditLogData.cs
@@ -1,14 +1,13 @@
-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;
namespace Discord.Rest
{
+ ///
+ /// Represents an audit log data for an emoji creation.
+ ///
public class EmoteCreateAuditLogData : IAuditLogData
{
private EmoteCreateAuditLogData(ulong id, string name)
@@ -25,7 +24,19 @@ internal static EmoteCreateAuditLogData Create(BaseDiscordClient discord, Model
return new EmoteCreateAuditLogData(entry.TargetId.Value, emoteName);
}
+ ///
+ /// Gets the snowflake ID of the created emoji.
+ ///
+ ///
+ /// An representing the snowflake identifier for the created emoji.
+ ///
public ulong EmoteId { get; }
+ ///
+ /// Gets the name of the created emoji.
+ ///
+ ///
+ /// A string containing the name of the created emoji.
+ ///
public string Name { get; }
}
}
diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/EmoteDeleteAuditLogData.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/EmoteDeleteAuditLogData.cs
index d0a11191f4..2ce6acfbf4 100644
--- a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/EmoteDeleteAuditLogData.cs
+++ b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/EmoteDeleteAuditLogData.cs
@@ -1,10 +1,13 @@
-using System.Linq;
+using System.Linq;
using Model = Discord.API.AuditLog;
using EntryModel = Discord.API.AuditLogEntry;
namespace Discord.Rest
{
+ ///
+ /// Represents an audit log data for an emoji deletion.
+ ///
public class EmoteDeleteAuditLogData : IAuditLogData
{
private EmoteDeleteAuditLogData(ulong id, string name)
@@ -22,7 +25,19 @@ internal static EmoteDeleteAuditLogData Create(BaseDiscordClient discord, Model
return new EmoteDeleteAuditLogData(entry.TargetId.Value, emoteName);
}
+ ///
+ /// Gets the snowflake ID of the deleted emoji.
+ ///
+ ///
+ /// An representing the snowflake identifier for the deleted emoji.
+ ///
public ulong EmoteId { get; }
+ ///
+ /// Gets the name of the deleted emoji.
+ ///
+ ///
+ /// A string containing the name of the deleted emoji.
+ ///
public string Name { get; }
}
}
diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/EmoteUpdateAuditLogData.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/EmoteUpdateAuditLogData.cs
index 60020bcaa4..506797707e 100644
--- a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/EmoteUpdateAuditLogData.cs
+++ b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/EmoteUpdateAuditLogData.cs
@@ -1,10 +1,13 @@
-using System.Linq;
+using System.Linq;
using Model = Discord.API.AuditLog;
using EntryModel = Discord.API.AuditLogEntry;
namespace Discord.Rest
{
+ ///
+ /// Represents an audit log data for an emoji update.
+ ///
public class EmoteUpdateAuditLogData : IAuditLogData
{
private EmoteUpdateAuditLogData(ulong id, string oldName, string newName)
@@ -24,8 +27,26 @@ internal static EmoteUpdateAuditLogData Create(BaseDiscordClient discord, Model
return new EmoteUpdateAuditLogData(entry.TargetId.Value, oldName, newName);
}
+ ///
+ /// Gets the snowflake ID of the updated emoji.
+ ///
+ ///
+ /// An representing the snowflake identifier of the updated emoji.
+ ///
public ulong EmoteId { get; }
+ ///
+ /// Gets the new name of the updated emoji.
+ ///
+ ///
+ /// A string containing the new name of the updated emoji.
+ ///
public string NewName { get; }
+ ///
+ /// Gets the old name of the updated emoji.
+ ///
+ ///
+ /// A string containing the old name of the updated emoji.
+ ///
public string OldName { get; }
}
}
diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/GuildInfo.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/GuildInfo.cs
index 90865ef722..4e830240a5 100644
--- a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/GuildInfo.cs
+++ b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/GuildInfo.cs
@@ -1,5 +1,8 @@
namespace Discord.Rest
{
+ ///
+ /// Represents information for a guild.
+ ///
public struct GuildInfo
{
internal GuildInfo(int? afkTimeout, DefaultMessageNotifications? defaultNotifs,
@@ -18,14 +21,66 @@ public struct GuildInfo
ContentFilterLevel = filter;
}
+ ///
+ /// Gets the amount of time (in seconds) a user must be inactive in a voice channel for until they are
+ /// automatically moved to the AFK voice channel.
+ ///
+ ///
+ /// An representing the amount of time in seconds for a user to be marked as inactive
+ /// and moved into the AFK voice channel.
+ ///
public int? AfkTimeout { get; }
+ ///
+ /// Gets the default message notifications for users who haven't explicitly set their notification settings.
+ ///
public DefaultMessageNotifications? DefaultMessageNotifications { get; }
+ ///
+ /// Gets the ID of the AFK voice channel for this guild.
+ ///
+ ///
+ /// An representing the snowflake identifier of the AFK voice channel; null if
+ /// none is set.
+ ///
public ulong? AfkChannelId { get; }
+ ///
+ /// Gets the name of this guild.
+ ///
+ ///
+ /// A string containing the name of this guild.
+ ///
public string Name { get; }
+ ///
+ /// Gets the ID of the region hosting this guild's voice channels.
+ ///
public string RegionId { get; }
+ ///
+ /// Gets the ID of this guild's icon.
+ ///
+ ///
+ /// An identifier for the splash image; null if none is set.
+ ///
public string IconHash { get; }
+ ///
+ /// Gets the level of requirements a user must fulfill before being allowed to post messages in this guild.
+ ///
+ ///
+ /// The level of requirements.
+ ///
public VerificationLevel? VerificationLevel { get; }
+ ///
+ /// Gets the owner of this guild.
+ ///
+ ///
+ /// An object representing the owner of this guild.
+ ///
public IUser Owner { get; }
+ ///
+ /// Gets the level of Multi-Factor Authentication requirements a user must fulfill before being allowed to
+ /// perform administrative actions in this guild.
+ ///
+ ///
+ /// The level of MFA requirement.
+ ///
public MfaLevel? MfaLevel { get; }
public int? ContentFilterLevel { get; }
}