From c7b236ddf5d7324dd8c1513ccd528a7a45d0031f Mon Sep 17 00:00:00 2001
From: Still Hsu <341464@gmail.com>
Date: Sun, 6 May 2018 15:58:23 +0800
Subject: [PATCH] Add more IGuild docs
---
.../Entities/Guilds/IGuild.cs | 98 ++++++++++++++-----
1 file changed, 72 insertions(+), 26 deletions(-)
diff --git a/src/Discord.Net.Core/Entities/Guilds/IGuild.cs b/src/Discord.Net.Core/Entities/Guilds/IGuild.cs
index 17f5ac328..064a9997f 100644
--- a/src/Discord.Net.Core/Entities/Guilds/IGuild.cs
+++ b/src/Discord.Net.Core/Entities/Guilds/IGuild.cs
@@ -13,11 +13,17 @@ namespace Discord
///
/// Gets the name of this guild.
///
+ ///
+ /// A string containing the name of this guild.
+ ///
string Name { get; }
///
/// 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, if one is set.
+ /// 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.
+ ///
int AFKTimeout { get; }
///
/// Determines if this guild is embeddable (i.e. can use widget).
@@ -34,33 +40,56 @@ namespace Discord
/// 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.
+ ///
MfaLevel MfaLevel { get; }
///
/// Gets the level of requirements a user must fulfill before being allowed to post messages in this guild.
///
+ ///
+ /// The level of requirements.
+ ///
VerificationLevel VerificationLevel { get; }
///
- /// Returns the ID of this guild's icon, or null if none is set.
+ /// Gets the ID of this guild's icon.
///
+ ///
+ /// An identifier for the splash image; null if none is set.
+ ///
string IconId { get; }
///
- /// Returns the URL of this guild's icon, or null if none is set.
+ /// Gets the URL of this guild's icon.
///
+ ///
+ /// A URL pointing to the guild's icon; null if none is set.
+ ///
string IconUrl { get; }
///
- /// Returns the ID of this guild's splash image, or null if none is set.
+ /// Gets the ID of this guild's splash image.
///
+ ///
+ /// An identifier for the splash image; null if none is set.
+ ///
string SplashId { get; }
///
- /// Returns the URL of this guild's splash image, or null if none is set.
+ /// Gets the URL of this guild's splash image.
///
+ ///
+ /// A URL pointing to the guild's splash image; null if none is set.
+ ///
string SplashUrl { get; }
///
/// Determines if this guild is currently connected and ready to be used.
///
+ ///
+ ///
+ /// This property only applies to a WebSocket-based client.
+ ///
+ /// This boolean is used to determine if the guild is currently connected to the WebSocket and is ready to be used/accessed.
+ ///
///
- /// Returns true if this guild is currently connected and ready to be used. Only applies
- /// to the WebSocket client.
+ /// true if this guild is currently connected and ready to be used; otherwise false.
///
bool Available { get; }
@@ -143,7 +172,7 @@ namespace Discord
///
Task ModifyEmbedAsync(Action func, RequestOptions options = null);
///
- /// Bulk modifies the order of channels in this guild.
+ /// Bulk-modifies the order of channels in this guild.
///
/// The properties used to modify the channel positions with.
/// The options to be used when sending the request.
@@ -152,17 +181,21 @@ namespace Discord
///
Task ReorderChannelsAsync(IEnumerable args, RequestOptions options = null);
///
- /// Bulk modifies the order of roles in this guild.
+ /// Bulk-modifies the order of roles in this guild.
///
/// The properties used to modify the role positions with.
/// The options to be used when sending the request.
- Task ReorderRolesAsync(IEnumerable args, RequestOptions options = null);
///
/// An awaitable .
///
+ Task ReorderRolesAsync(IEnumerable args, RequestOptions options = null);
///
- /// Leaves this guild. If you are the owner, use instead.
+ /// Leaves this guild.
///
+ ///
+ /// This method will make the currently logged-in user leave the guild. If the user is the owner, use
+ /// instead.
+ ///
/// The options to be used when sending the request.
///
/// An awaitable .
@@ -178,7 +211,7 @@ namespace Discord
///
Task> GetBansAsync(RequestOptions options = null);
///
- /// Bans the provided user from this guild and optionally prunes their recent messages.
+ /// Bans the user from this guild and optionally prunes their recent messages.
///
/// The user to ban.
///
@@ -192,9 +225,9 @@ namespace Discord
///
Task AddBanAsync(IUser user, int pruneDays = 0, string reason = null, RequestOptions options = null);
///
- /// Bans the provided user ID from this guild and optionally prunes their recent messages.
+ /// Bans the user from this guild and optionally prunes their recent messages.
///
- /// The ID of the user to ban.
+ /// The snowflake ID of the user to ban.
///
/// The number of days to remove messages from this user for - must be between [0, 7].
///
@@ -389,12 +422,19 @@ namespace Discord
///
/// Gets a collection of all invites to this guild.
///
+ /// The options to be used when sending the request.
+ ///
+ /// An awaitable containing a collection of invites found within this guild.
+ ///
Task> GetInvitesAsync(RequestOptions options = null);
///
- /// Gets the role in this guild with the provided ID, or null if not found.
+ /// Gets a role in this guild.
///
/// The role ID.
+ ///
+ /// A role that matches the provided snowflake identifier; null if none is found.
+ ///
IRole GetRole(ulong id);
///
/// Creates a new role with the provided name.
@@ -412,25 +452,30 @@ namespace Discord
///
/// Gets a collection of all users in this guild.
///
- /// The that determines whether the object should be fetched from
- /// cache.
+ ///
+ /// This method retrieves all users found within this guild.
+ ///
+ /// This may return an incomplete list on the WebSocket implementation.
+ ///
+ ///
+ ///
+ /// 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 users found within this guild.
///
- ///
- /// This may return an incomplete list on the WebSocket implementation because Discord only sends offline
- /// users on large guilds.
- ///
Task> GetUsersAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
///
- /// Gets the user in this guild with the provided ID, or null if not found.
+ /// Gets a user found in this guild.
///
- /// The user ID.
- /// The that determines whether the object should be fetched from cache.
+ /// The user ID to search for.
+ /// The that determines whether the object should be fetched from
+ /// cache.
/// The options to be used when sending the request.
///
- /// An awaitable containing the guild user with the specified ID, otherwise null.
+ /// An awaitable containing the guild user with the specified ID; null if none is
+ /// found.
///
Task GetUserAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
///
@@ -499,7 +544,8 @@ namespace Discord
/// The guild emote ID.
/// The options to be used when sending the request.
///
- /// An awaitable containing the emote found with the specified ID, or null if not found.
+ /// An awaitable containing the emote found with the specified ID; null if none is
+ /// found.
///
Task GetEmoteAsync(ulong id, RequestOptions options = null);
///