Add more IGuild docs

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

@@ -13,11 +13,17 @@ namespace Discord
         /// <summary>
         ///     Gets the name of this guild.
         /// </summary>
+        /// <returns>
+        ///     A string containing the name of this guild.
+        /// </returns>
         string Name { get; }
         /// <summary>
         ///     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.
         /// </summary>
+        /// <returns>
+        ///     The amount of time in seconds for a user to be marked as inactive and moved into the AFK voice channel.
+        /// </returns>
         int AFKTimeout { get; }
         /// <summary>
         ///     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.
         /// </summary>
+        /// <returns>
+        ///     The level of MFA requirement.
+        /// </returns>
         MfaLevel MfaLevel { get; }
         /// <summary>
         ///     Gets the level of requirements a user must fulfill before being allowed to post messages in this guild.
         /// </summary>
+        /// <returns>
+        ///     The level of requirements.
+        /// </returns>
         VerificationLevel VerificationLevel { get; }
         /// <summary>
-        ///     Returns the ID of this guild's icon, or <c>null</c> if none is set.
+        ///     Gets the ID of this guild's icon.
         /// </summary>
+        /// <returns>
+        ///     An identifier for the splash image; <c>null</c> if none is set.
+        /// </returns>
         string IconId { get; }
         /// <summary>
-        ///     Returns the URL of this guild's icon, or <c>null</c> if none is set.
+        ///     Gets the URL of this guild's icon.
         /// </summary>
+        /// <returns>
+        ///     A URL pointing to the guild's icon; <c>null</c> if none is set.
+        /// </returns>
         string IconUrl { get; }
         /// <summary>
-        ///     Returns the ID of this guild's splash image, or <c>null</c> if none is set.
+        ///     Gets the ID of this guild's splash image.
         /// </summary>
+        /// <returns>
+        ///     An identifier for the splash image; <c>null</c> if none is set.
+        /// </returns>
         string SplashId { get; }
         /// <summary>
-        ///     Returns the URL of this guild's splash image, or <c>null</c> if none is set.
+        ///     Gets the URL of this guild's splash image.
         /// </summary>
+        /// <returns>
+        ///     A URL pointing to the guild's splash image; <c>null</c> if none is set.
+        /// </returns>
         string SplashUrl { get; }
         /// <summary>
         ///     Determines if this guild is currently connected and ready to be used.
         /// </summary>
+        /// <remarks>
+        ///     <note>
+        ///         This property only applies to a WebSocket-based client.
+        ///     </note>
+        ///     This boolean is used to determine if the guild is currently connected to the WebSocket and is ready to be used/accessed.
+        /// </remarks>
         /// <returns>
-        ///     Returns <c>true</c> if this guild is currently connected and ready to be used. Only applies
-        ///     to the WebSocket client.
+        ///     <c>true</c> if this guild is currently connected and ready to be used; otherwise <c>false</c>.
         /// </returns>
         bool Available { get; }
 
@@ -143,7 +172,7 @@ namespace Discord
         /// </returns>
         Task ModifyEmbedAsync(Action<GuildEmbedProperties> func, RequestOptions options = null);
         /// <summary>
-        ///     Bulk modifies the order of channels in this guild.
+        ///     Bulk-modifies the order of channels in this guild.
         /// </summary>
         /// <param name="args">The properties used to modify the channel positions with.</param>
         /// <param name="options">The options to be used when sending the request.</param>
@@ -152,17 +181,21 @@ namespace Discord
         /// </returns>
         Task ReorderChannelsAsync(IEnumerable<ReorderChannelProperties> args, RequestOptions options = null);
         /// <summary>
-        ///     Bulk modifies the order of roles in this guild.
+        ///     Bulk-modifies the order of roles in this guild.
         /// </summary>
         /// <param name="args">The properties used to modify the role positions with.</param>
         /// <param name="options">The options to be used when sending the request.</param>
-        Task ReorderRolesAsync(IEnumerable<ReorderRoleProperties> args, RequestOptions options = null);
         /// <returns>
         ///     An awaitable <see cref="Task"/>.
         /// </returns>
+        Task ReorderRolesAsync(IEnumerable<ReorderRoleProperties> args, RequestOptions options = null);
         /// <summary>
-        ///     Leaves this guild. If you are the owner, use <see cref="IDeletable.DeleteAsync" /> instead.
+        ///     Leaves this guild.
         /// </summary>
+        /// <remarks>
+        ///     This method will make the currently logged-in user leave the guild. If the user is the owner, use 
+        ///     <see cref="IDeletable.DeleteAsync" /> instead.
+        /// </remarks>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
         ///     An awaitable <see cref="Task"/>.
@@ -178,7 +211,7 @@ namespace Discord
         /// </returns>
         Task<IReadOnlyCollection<IBan>> GetBansAsync(RequestOptions options = null);
         /// <summary>
-        ///     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.
         /// </summary>
         /// <param name="user">The user to ban.</param>
         /// <param name="pruneDays">
@@ -192,9 +225,9 @@ namespace Discord
         /// </returns>
         Task AddBanAsync(IUser user, int pruneDays = 0, string reason = null, RequestOptions options = null);
         /// <summary>
-        ///     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.
         /// </summary>
-        /// <param name="userId">The ID of the user to ban.</param>
+        /// <param name="userId">The snowflake ID of the user to ban.</param>
         /// <param name="pruneDays">
         /// The number of days to remove messages from this user for - must be between [0, 7].
         /// </param>
@@ -389,12 +422,19 @@ namespace Discord
         /// <summary>
         ///     Gets a collection of all invites to this guild.
         /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/> containing a collection of invites found within this guild.
+        /// </returns>
         Task<IReadOnlyCollection<IInviteMetadata>> GetInvitesAsync(RequestOptions options = null);
 
         /// <summary>
-        ///     Gets the role in this guild with the provided ID, or <c>null</c> if not found.
+        ///     Gets a role in this guild.
         /// </summary>
         /// <param name="id">The role ID.</param>
+        /// <returns>
+        ///     A role that matches the provided snowflake identifier; <c>null</c> if none is found.
+        /// </returns>
         IRole GetRole(ulong id);
         /// <summary>
         ///     Creates a new role with the provided name.
@@ -412,25 +452,30 @@ namespace Discord
         /// <summary>
         ///     Gets a collection of all users in this guild.
         /// </summary>
-        /// <param name="mode">The <see cref="CacheMode"/> that determines whether the object should be fetched from
-        /// cache.</param>
+        /// <remarks>
+        ///     This method retrieves all users found within this guild.
+        ///     <note>
+        ///         This may return an incomplete list on the WebSocket implementation.
+        ///     </note>
+        /// </remarks>
+        /// <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 collection of users found within this guild.
         /// </returns>
-        /// <remarks>
-        ///     This may return an incomplete list on the WebSocket implementation because Discord only sends offline
-        ///     users on large guilds.
-        /// </remarks>
         Task<IReadOnlyCollection<IGuildUser>> GetUsersAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
-        ///     Gets the user in this guild with the provided ID, or <c>null</c> if not found.
+        ///     Gets a user found in this guild.
         /// </summary>
-        /// <param name="id">The user ID.</param>
-        /// <param name="mode">The <see cref="CacheMode"/> that determines whether the object should be fetched from cache.</param>
+        /// <param name="id">The user ID to search for.</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 the guild user with the specified ID, otherwise <c>null</c>.
+        ///     An awaitable <see cref="Task"/> containing the guild user with the specified ID; <c>null</c> if none is
+        ///     found.
         /// </returns>
         Task<IGuildUser> GetUserAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
@@ -499,7 +544,8 @@ namespace Discord
         /// <param name="id">The guild emote ID.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing the emote found with the specified ID, or <c>null</c> if not found.
+        ///     An awaitable <see cref="Task"/> containing the emote found with the specified ID; <c>null</c> if none is
+        ///     found.
         /// </returns>
         Task<GuildEmote> GetEmoteAsync(ulong id, RequestOptions options = null);
         /// <summary>