Merge pull request #7 from CasinoBoyale/Casino-Docs

Added some REST documentation

src/Discord.Net.Core/Entities/ISnowflakeEntity.cs

@@ -6,7 +6,7 @@ namespace Discord
     public interface ISnowflakeEntity : IEntity<ulong>
     {
         /// <summary>
-        ///     Gets when the snowflake is created.
+        ///     Gets when the snowflake was created.
         /// </summary>
         /// <returns>
         ///     A <see cref="DateTimeOffset"/> representing when the entity was first created.

src/Discord.Net.Rest/Entities/Channels/RestDMChannel.cs

@@ -15,9 +15,19 @@ namespace Discord.Rest
     [DebuggerDisplay(@"{DebuggerDisplay,nq}")]
     public class RestDMChannel : RestChannel, IDMChannel, IRestPrivateChannel, IRestMessageChannel
     {
+        /// <summary>
+        ///     Gets the current logged-in user.
+        /// </summary>
         public RestUser CurrentUser { get; }
+
+        /// <summary>
+        ///     Gets the recipient of the channel.
+        /// </summary>
         public RestUser Recipient { get; }
 
+        /// <summary>
+        ///     Gets a collection that is the current logged-in user and the recipient.
+        /// </summary>
         public IReadOnlyCollection<RestUser> Users => ImmutableArray.Create(CurrentUser, Recipient);
 
         internal RestDMChannel(BaseDiscordClient discord, ulong id, ulong recipientId)
@@ -132,6 +142,12 @@ namespace Discord.Rest
         public IDisposable EnterTypingState(RequestOptions options = null)
             => ChannelHelper.EnterTypingState(this, Discord, options);
 
+        /// <summary>
+        ///     Gets a string that represents the Username#Discriminator of the recipient.
+        /// </summary>
+        /// <returns>
+        ///     A string that resolves to the Recipient of this channel.
+        /// </returns>
         public override string ToString() => $"@{Recipient}";
         private string DebuggerDisplay => $"@{Recipient} ({Id}, DM)";
 

src/Discord.Net.Rest/Entities/Guilds/RestGuild.cs

@@ -59,7 +59,14 @@ namespace Discord.Rest
         /// <inheritdoc />
         public string SplashUrl => CDN.GetGuildSplashUrl(Id, SplashId);
 
+        /// <summary>
+        ///     Gets the built-in role containing all users in this guild.
+        /// </summary>
         public RestRole EveryoneRole => GetRole(Id);
+
+        /// <summary>
+        ///     Gets a collection of all roles in this guild.
+        /// </summary>
         public IReadOnlyCollection<RestRole> Roles => _roles.ToReadOnlyCollection();
         /// <inheritdoc />
         public IReadOnlyCollection<GuildEmote> Emotes => _emotes;
@@ -170,10 +177,38 @@ namespace Discord.Rest
             => GuildHelper.LeaveAsync(this, Discord, options);
 
         //Bans
+        //Bans
+        /// <summary>
+        ///     Gets a collection of all users banned in this guild.
+        /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains a read-only collection of
+        ///     ban objects that this guild currently possesses, with each object containing the user banned and reason
+        ///     behind the ban.
+        /// </returns>
         public Task<IReadOnlyCollection<RestBan>> GetBansAsync(RequestOptions options = null)
             => GuildHelper.GetBansAsync(this, Discord, options);
+        /// <summary>
+        ///     Gets a ban object for a banned user.
+        /// </summary>
+        /// <param name="user">The banned user.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains a ban object, which
+        ///     contains the user information and the reason for the ban; <c>null</c> if the ban entry cannot be found.
+        /// </returns>
         public Task<RestBan> GetBanAsync(IUser user, RequestOptions options = null)
             => GuildHelper.GetBanAsync(this, Discord, user.Id, options);
+        /// <summary>
+        ///     Gets a ban object for a banned user.
+        /// </summary>
+        /// <param name="userId">The snowflake identifier for the banned user.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains a ban object, which
+        ///     contains the user information and the reason for the ban; <c>null</c> if the ban entry cannot be found.
+        /// </returns>
         public Task<RestBan> GetBanAsync(ulong userId, RequestOptions options = null)
             => GuildHelper.GetBanAsync(this, Discord, userId, options);
 
@@ -192,36 +227,110 @@ namespace Discord.Rest
             => GuildHelper.RemoveBanAsync(this, Discord, userId, options);
 
         //Channels
+        /// <summary>
+        ///     Gets a collection of all channels in this guild.
+        /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains a read-only collection of
+        ///     generic channels found within this guild.
+        /// </returns>
         public Task<IReadOnlyCollection<RestGuildChannel>> GetChannelsAsync(RequestOptions options = null)
             => GuildHelper.GetChannelsAsync(this, Discord, options);
+
+        /// <summary>
+        ///     Gets a channel in this guild.
+        /// </summary>
+        /// <param name="id">The snowflake identifier for the channel.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains the generic channel
+        ///     associated with the specified <paramref name="id"/>; <c>null</c> if none is found.
+        /// </returns>
         public Task<RestGuildChannel> GetChannelAsync(ulong id, RequestOptions options = null)
             => GuildHelper.GetChannelAsync(this, Discord, id, options);
+
+        /// <summary>
+        ///     Gets a text channel in this guild.
+        /// </summary>
+        /// <param name="id">The snowflake identifier for the text channel.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains the text channel
+        ///     associated with the specified <paramref name="id"/>; <c>null</c> if none is found.
+        /// </returns>
         public async Task<RestTextChannel> GetTextChannelAsync(ulong id, RequestOptions options = null)
         {
             var channel = await GuildHelper.GetChannelAsync(this, Discord, id, options).ConfigureAwait(false);
             return channel as RestTextChannel;
         }
+
+        /// <summary>
+        ///     Gets a collection of all text channels in this guild.
+        /// </summary>
+        /// <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>
+        ///     A task that represents the asynchronous get operation. The task result contains a read-only collection of
+        ///     message channels found within this guild.
+        /// </returns>
         public async Task<IReadOnlyCollection<RestTextChannel>> GetTextChannelsAsync(RequestOptions options = null)
         {
             var channels = await GuildHelper.GetChannelsAsync(this, Discord, options).ConfigureAwait(false);
             return channels.Select(x => x as RestTextChannel).Where(x => x != null).ToImmutableArray();
         }
+
+        /// <summary>
+        ///     Gets a voice channel in this guild.
+        /// </summary>
+        /// <param name="id">The snowflake identifier for the voice channel.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains the voice channel associated
+        ///     with the specified <paramref name="id"/>; <c>null</c> if none is found.
+        /// </returns>
         public async Task<RestVoiceChannel> GetVoiceChannelAsync(ulong id, RequestOptions options = null)
         {
             var channel = await GuildHelper.GetChannelAsync(this, Discord, id, options).ConfigureAwait(false);
             return channel as RestVoiceChannel;
         }
+
+        /// <summary>
+        ///     Gets a collection of all voice channels in this guild.
+        /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains a read-only collection of
+        ///     voice channels found within this guild.
+        /// </returns>
         public async Task<IReadOnlyCollection<RestVoiceChannel>> GetVoiceChannelsAsync(RequestOptions options = null)
         {
             var channels = await GuildHelper.GetChannelsAsync(this, Discord, options).ConfigureAwait(false);
             return channels.Select(x => x as RestVoiceChannel).Where(x => x != null).ToImmutableArray();
         }
+
+        /// <summary>
+        ///     Gets a collection of all category channels in this guild.
+        /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains a read-only collection of
+        ///     category channels found within this guild.
+        /// </returns>
         public async Task<IReadOnlyCollection<RestCategoryChannel>> GetCategoryChannelsAsync(RequestOptions options = null)
         {
             var channels = await GuildHelper.GetChannelsAsync(this, Discord, options).ConfigureAwait(false);
             return channels.Select(x => x as RestCategoryChannel).Where(x => x != null).ToImmutableArray();
         }
 
+        /// <summary>
+        ///     Gets the AFK voice channel in this guild.
+        /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains the voice channel that the
+        ///     AFK users will be moved to after they have idled for too long; <c>null</c> if none is set.
+        /// </returns>
         public async Task<RestVoiceChannel> GetAFKChannelAsync(RequestOptions options = null)
         {
             var afkId = AFKChannelId;
@@ -232,6 +341,15 @@ namespace Discord.Rest
             }
             return null;
         }
+
+        /// <summary>
+        ///     Gets the first viewable text channel in this guild.
+        /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains the first viewable text
+        ///     channel in this guild; <c>null</c> if none is found.
+        /// </returns>
         public async Task<RestTextChannel> GetDefaultChannelAsync(RequestOptions options = null)
         {
             var channels = await GetTextChannelsAsync(options).ConfigureAwait(false);
@@ -241,6 +359,15 @@ namespace Discord.Rest
                 .OrderBy(c => c.Position)
                 .FirstOrDefault();
         }
+
+        /// <summary>
+        ///     Gets the embed channel (i.e. the channel set in the guild's widget settings) in this guild.
+        /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains the embed channel set
+        ///     within the server's widget settings; <c>null</c> if none is set.
+        /// </returns>
         public async Task<RestGuildChannel> GetEmbedChannelAsync(RequestOptions options = null)
         {
             var embedId = EmbedChannelId;
@@ -248,6 +375,15 @@ namespace Discord.Rest
                 return await GuildHelper.GetChannelAsync(this, Discord, embedId.Value, options).ConfigureAwait(false);
             return null;
         }
+
+        /// <summary>
+        ///     Gets the first viewable text channel in this guild.
+        /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains the first viewable text
+        ///     channel in this guild; <c>null</c> if none is found.
+        /// </returns>
         public async Task<RestTextChannel> GetSystemChannelAsync(RequestOptions options = null)
         {
             var systemId = SystemChannelId;
@@ -301,6 +437,14 @@ namespace Discord.Rest
             => GuildHelper.CreateIntegrationAsync(this, Discord, id, type, options);
 
         //Invites
+        /// <summary>
+        ///     Gets a collection of all invites in this guild.
+        /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains a read-only collection of
+        ///     invite metadata, each representing information for an invite found within this guild.
+        /// </returns>
         public Task<IReadOnlyCollection<RestInviteMetadata>> GetInvitesAsync(RequestOptions options = null)
             => GuildHelper.GetInvitesAsync(this, Discord, options);
         /// <summary>
@@ -314,6 +458,13 @@ namespace Discord.Rest
             => GuildHelper.GetVanityInviteAsync(this, Discord, options);
 
         //Roles
+        /// <summary>
+        ///     Gets a role in this guild.
+        /// </summary>
+        /// <param name="id">The snowflake identifier for the role.</param>
+        /// <returns>
+        ///     A role that is associated with the specified <paramref name="id"/>; <c>null</c> if none is found.
+        /// </returns>
         public RestRole GetRole(ulong id)
         {
             if (_roles.TryGetValue(id, out RestRole value))
@@ -321,6 +472,18 @@ namespace Discord.Rest
             return null;
         }
 
+        /// <summary>
+        ///     Creates a new role with the provided name.
+        /// </summary>
+        /// <param name="name">The new name for the role.</param>
+        /// <param name="permissions">The guild permission that the role should possess.</param>
+        /// <param name="color">The color of the role.</param>
+        /// <param name="isHoisted">Whether the role is separated from others on the sidebar.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous creation operation. The task result contains the newly created
+        ///     role.
+        /// </returns>
         public async Task<RestRole> CreateRoleAsync(string name, GuildPermissions? permissions = default(GuildPermissions?), Color? color = default(Color?),
             bool isHoisted = false, RequestOptions options = null)
         {
@@ -330,26 +493,113 @@ namespace Discord.Rest
         }
 
         //Users
+        /// <summary>
+        ///     Gets a collection of all users in this guild.
+        /// </summary>
+        /// <remarks>
+        ///     This method retrieves all users found within this guild.
+        /// </remarks>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains a collection of guild
+        ///     users found within this guild.
+        /// </returns>
         public IAsyncEnumerable<IReadOnlyCollection<RestGuildUser>> GetUsersAsync(RequestOptions options = null)
             => GuildHelper.GetUsersAsync(this, Discord, null, null, options);
+
+        /// <summary>
+        ///     Gets a user from this guild.
+        /// </summary>
+        /// <remarks>
+        ///     This method retrieves a user found within this guild.
+        /// </remarks>
+        /// <param name="id">The snowflake identifier of the user.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains the guild user
+        ///     associated with the specified <paramref name="id"/>; <c>null</c> if none is found.
+        /// </returns>
         public Task<RestGuildUser> GetUserAsync(ulong id, RequestOptions options = null)
             => GuildHelper.GetUserAsync(this, Discord, id, options);
+
+        /// <summary>
+        ///     Gets the current user for this guild.
+        /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains the currently logged-in
+        ///     user within this guild.
+        /// </returns>
         public Task<RestGuildUser> GetCurrentUserAsync(RequestOptions options = null)
             => GuildHelper.GetUserAsync(this, Discord, Discord.CurrentUser.Id, options);
+
+        /// <summary>
+        ///     Gets the owner of this guild.
+        /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains the owner of this guild.
+        /// </returns>
         public Task<RestGuildUser> GetOwnerAsync(RequestOptions options = null)
             => GuildHelper.GetUserAsync(this, Discord, OwnerId, options);
 
         /// <inheritdoc />
+        /// <summary>
+        ///     Prunes inactive users.
+        /// </summary>
+        /// <remarks>
+        ///     <para>
+        ///         This method removes all users that have not logged on in the provided number of <paramref name="days"/>.
+        ///     </para>
+        ///     <para>
+        ///         If <paramref name="simulate" /> is <c>true</c>, this method will only return the number of users that
+        ///         would be removed without kicking the users.
+        ///     </para>
+        /// </remarks>
+        /// <param name="days">The number of days required for the users to be kicked.</param>
+        /// <param name="simulate">Whether this prune action is a simulation.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous prune operation. The task result contains the number of users to
+        ///     be or has been removed from this guild.
+        /// </returns>
         public Task<int> PruneUsersAsync(int days = 30, bool simulate = false, RequestOptions options = null)
             => GuildHelper.PruneUsersAsync(this, Discord, days, simulate, options);
 
         //Audit logs
+        /// <summary>
+        ///     Gets the specified number of audit log entries for this guild.
+        /// </summary>
+        /// <param name="limit">The number of audit log entries to fetch.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains a read-only collection
+        ///     of the requested audit log entries.
+        /// </returns>
         public IAsyncEnumerable<IReadOnlyCollection<RestAuditLogEntry>> GetAuditLogsAsync(int limit, RequestOptions options = null)
             => GuildHelper.GetAuditLogsAsync(this, Discord, null, limit, options);
 
         //Webhooks
+        /// <summary>
+        ///     Gets a webhook found within this guild.
+        /// </summary>
+        /// <param name="id">The identifier for the webhook.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains the webhook with the
+        ///     specified <paramref name="id"/>; <c>null</c> if none is found.
+        /// </returns>
         public Task<RestWebhook> GetWebhookAsync(ulong id, RequestOptions options = null)
             => GuildHelper.GetWebhookAsync(this, Discord, id, options);
+
+        /// <summary>
+        ///     Gets a collection of all webhook from this guild.
+        /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains a read-only collection
+        ///     of webhooks found within the guild.
+        /// </returns>
         public Task<IReadOnlyCollection<RestWebhook>> GetWebhooksAsync(RequestOptions options = null)
             => GuildHelper.GetWebhooksAsync(this, Discord, options);
 

src/Discord.Net.Rest/Entities/Invites/RestInvite.cs

@@ -62,6 +62,12 @@ namespace Discord.Rest
         public Task DeleteAsync(RequestOptions options = null)
             => InviteHelper.DeleteAsync(this, Discord, options);
 
+        /// <summary>
+        ///     Gets the URL of the invite.
+        /// </summary>
+        /// <returns>
+        ///     A string that resolves to the Url of the invite.
+        /// </returns>
         public override string ToString() => Url;
         private string DebuggerDisplay => $"{Url} ({GuildName} / {ChannelName})";
 

src/Discord.Net.Rest/Entities/Users/RestUser.cs

@@ -65,6 +65,13 @@ namespace Discord.Rest
             Update(model);
         }
 
+        /// <summary>
+        ///     Returns a direct message channel to this user, or create one if it does not already exist.
+        /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains a rest DM channel where the user is the recipient.
+        /// </returns>
         public Task<RestDMChannel> GetOrCreateDMChannelAsync(RequestOptions options = null)
             => UserHelper.CreateDMChannelAsync(this, Discord, options);
 
@@ -80,7 +87,7 @@ namespace Discord.Rest
         ///     Gets the Username#Descriminator of the user.
         /// </summary>
         /// <returns>
-        ///     A string that is the Username#Descriminator of the user.
+        ///     A string that resolves to Username#Descriminator of the user.
         /// </returns>
         public override string ToString() => $"{Username}#{Discriminator}";
         private string DebuggerDisplay => $"{Username}#{Discriminator} ({Id}{(IsBot ? ", Bot" : "")})";

src/Discord.Net.WebSocket/Entities/Channels/SocketDMChannel.cs

@@ -25,6 +25,10 @@ namespace Discord.WebSocket
 
         /// <inheritdoc />
         public IReadOnlyCollection<SocketMessage> CachedMessages => _messages?.Messages ?? ImmutableArray.Create<SocketMessage>();
+
+        /// <summary>
+        ///     Gets a collection that is the current logged-in user and the recipient.
+        /// </summary>
         public new IReadOnlyCollection<SocketUser> Users => ImmutableArray.Create(Discord.CurrentUser, Recipient);
 
         internal SocketDMChannel(DiscordSocketClient discord, ulong id, SocketGlobalUser recipient)
@@ -81,8 +85,32 @@ namespace Discord.WebSocket
         /// </returns>
         public IAsyncEnumerable<IReadOnlyCollection<IMessage>> GetMessagesAsync(int limit = DiscordConfig.MaxMessagesPerBatch, RequestOptions options = null)
             => SocketChannelHelper.GetMessagesAsync(this, Discord, _messages, null, Direction.Before, limit, CacheMode.AllowDownload, options);
+
+        /// <summary>
+        ///     Gets a collection of messages in this channel.
+        /// </summary>
+        /// <param name="fromMessageId">The ID of the starting message to get the messages from.</param>
+        /// <param name="dir">The direction of the messages to be gotten from.</param>
+        /// <param name="limit">The numbers of message to be gotten from.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     Paged collection of messages. Flattening the paginated response into a collection of messages with 
+        ///     <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> is required if you wish to access the messages.
+        /// </returns>
         public IAsyncEnumerable<IReadOnlyCollection<IMessage>> GetMessagesAsync(ulong fromMessageId, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch, RequestOptions options = null)
             => SocketChannelHelper.GetMessagesAsync(this, Discord, _messages, fromMessageId, dir, limit, CacheMode.AllowDownload, options);
+
+        /// <summary>
+        ///     Gets a collection of messages in this channel.
+        /// </summary>
+        /// <param name="fromMessage">The starting message to get the messages from.</param>
+        /// <param name="dir">The direction of the messages to be gotten from.</param>
+        /// <param name="limit">The numbers of message to be gotten from.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     Paged collection of messages. Flattening the paginated response into a collection of messages with 
+        ///     <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> is required if you wish to access the messages.
+        /// </returns>
         public IAsyncEnumerable<IReadOnlyCollection<IMessage>> GetMessagesAsync(IMessage fromMessage, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch, RequestOptions options = null)
             => SocketChannelHelper.GetMessagesAsync(this, Discord, _messages, fromMessage.Id, dir, limit, CacheMode.AllowDownload, options);
         /// <inheritdoc />