Merge pull request #4 from CasinoBoyale/docs/pre-release

Added documentation for SocketDMChannel, SocketGuildChannel, and SocketTextChannel

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

@@ -47,6 +47,14 @@ namespace Discord.Rest
         public Task CloseAsync(RequestOptions options = null)
             => ChannelHelper.DeleteAsync(this, Discord, options);
 
+
+        /// <summary>
+        ///     Gets a user in this channel from the provided <paramref name="id"/>.
+        /// </summary>
+        /// <param name="id">The snowflake identifier of the user.</param>
+        /// <returns>
+        ///     A <see cref="RestUser"/> object that is a recipient of this channel; otherwise <c>null</c>.
+        /// </returns>
         public RestUser GetUser(ulong id)
         {
             if (id == Recipient.Id)
@@ -175,10 +183,10 @@ namespace Discord.Rest
         /// <inheritdoc />
         async Task<IReadOnlyCollection<IMessage>> IMessageChannel.GetPinnedMessagesAsync(RequestOptions options)
             => await GetPinnedMessagesAsync(options).ConfigureAwait(false);
-
+        /// <inheritdoc />
         async Task<IUserMessage> IMessageChannel.SendFileAsync(string filePath, string text, bool isTTS, Embed embed, RequestOptions options)
             => await SendFileAsync(filePath, text, isTTS, embed, options).ConfigureAwait(false);
-
+        /// <inheritdoc />
         async Task<IUserMessage> IMessageChannel.SendFileAsync(Stream stream, string filename, string text, bool isTTS, Embed embed, RequestOptions options)
             => await SendFileAsync(stream, filename, text, isTTS, embed, options).ConfigureAwait(false);
         /// <inheritdoc />

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

@@ -72,6 +72,13 @@ namespace Discord.Rest
         public Task DeleteAsync(RequestOptions options = null)
             => ChannelHelper.DeleteAsync(this, Discord, options);
 
+        /// <summary>
+        ///     Gets the overwrite permissions of the specified <paramref name="user"/>.
+        /// </summary>
+        /// <param name="user">The user that you want to get the overwrite permissions for.</param>
+        /// <returns>
+        ///     The overwrite permissions for the requested user; otherwise <c>null</c>.
+        /// </returns>
         public OverwritePermissions? GetPermissionOverwrite(IUser user)
         {
             for (int i = 0; i < _overwrites.Length; i++)
@@ -81,6 +88,14 @@ namespace Discord.Rest
             }
             return null;
         }
+
+        /// <summary>
+        ///     Gets the overwrite permissions of the specified <paramref name="role"/>.
+        /// </summary>
+        /// <param name="role">The role that you want to get the overwrite permissions for.</param>
+        /// <returns>
+        ///     The overwrite permissions for the requested role; otherwise <c>null</c>.
+        /// </returns>
         public OverwritePermissions? GetPermissionOverwrite(IRole role)
         {
             for (int i = 0; i < _overwrites.Length; i++)
@@ -90,16 +105,45 @@ namespace Discord.Rest
             }
             return null;
         }
+
+        /// <summary>
+        ///     Adds an overwrite permission for the specified <paramref name="user"/>.
+        /// </summary>
+        /// <param name="user">The user you want the overwrite permission to apply to.</param>
+        /// <param name="perms">The overwrite permission you want to add.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/>.
+        /// </returns>
         public async Task AddPermissionOverwriteAsync(IUser user, OverwritePermissions perms, RequestOptions options = null)
         {
             await ChannelHelper.AddPermissionOverwriteAsync(this, Discord, user, perms, options).ConfigureAwait(false);
             _overwrites = _overwrites.Add(new Overwrite(user.Id, PermissionTarget.User, new OverwritePermissions(perms.AllowValue, perms.DenyValue)));
         }
+
+        /// <summary>
+        ///     Adds an overwrite permission for the specified <paramref name="role"/>.
+        /// </summary>
+        /// <param name="role">The role you want the overwrite permission to apply to.</param>
+        /// <param name="perms">The overwrite permission you want to add.</param>
+        /// <param name="options">The options to be used when sending the request. </param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/>.
+        /// </returns>
         public async Task AddPermissionOverwriteAsync(IRole role, OverwritePermissions perms, RequestOptions options = null)
         {
             await ChannelHelper.AddPermissionOverwriteAsync(this, Discord, role, perms, options).ConfigureAwait(false);
             _overwrites = _overwrites.Add(new Overwrite(role.Id, PermissionTarget.Role, new OverwritePermissions(perms.AllowValue, perms.DenyValue)));
         }
+
+        /// <summary>
+        ///     Removes an overwrite permission for the specified <paramref name="user"/>.
+        /// </summary>
+        /// <param name="user">The user you want to remove the overwrite permission from.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/>.
+        /// </returns>
         public async Task RemovePermissionOverwriteAsync(IUser user, RequestOptions options = null)
         {
             await ChannelHelper.RemovePermissionOverwriteAsync(this, Discord, user, options).ConfigureAwait(false);
@@ -113,6 +157,15 @@ namespace Discord.Rest
                 }
             }
         }
+
+        /// <summary>
+        ///     Removes an overwrite permission for the specified <paramref name="role"/>.
+        /// </summary>
+        /// <param name="role">The role you want the overwrite permissions to be removed from.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/>.
+        /// </returns>
         public async Task RemovePermissionOverwriteAsync(IRole role, RequestOptions options = null)
         {
             await ChannelHelper.RemovePermissionOverwriteAsync(this, Discord, role, options).ConfigureAwait(false);
@@ -127,11 +180,38 @@ namespace Discord.Rest
             }
         }
 
+        /// <summary>
+        ///     Gets the invites for this channel.
+        /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/> containing an <see cref="IReadOnlyCollection{RestInviteMetaData}"/>.
+        ///     <see cref="RestInviteMetadata"/> contains information such as, the number of times the invite has
+        ///     been used, who created the invite, and when the invite was created.
+        /// </returns>
         public async Task<IReadOnlyCollection<RestInviteMetadata>> GetInvitesAsync(RequestOptions options = null)
             => await ChannelHelper.GetInvitesAsync(this, Discord, options).ConfigureAwait(false);
+
+        /// <summary>
+        ///     Creates an invite for this channel.
+        /// </summary>
+        /// <param name="maxAge">The number of seconds that you want the invite to be valid for.</param>
+        /// <param name="maxUses">The number of times this invite can be used before it expires.</param>
+        /// <param name="isTemporary">Whether or not the invite grants temporary membership.</param>
+        /// <param name="isUnique">Whether to try reuse a similar invite or not.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/> containing a <see cref="RestInviteMetadata"/>.
+        /// </returns>
         public async Task<RestInviteMetadata> CreateInviteAsync(int? maxAge = 86400, int? maxUses = null, bool isTemporary = false, bool isUnique = false, RequestOptions options = null)
             => await ChannelHelper.CreateInviteAsync(this, Discord, maxAge, maxUses, isTemporary, isUnique, options).ConfigureAwait(false);
 
+        /// <summary>
+        ///     Gets the name of this channel.
+        /// </summary>
+        /// <returns>
+        ///     A string that is the name of this channel.
+        /// </returns>
         public override string ToString() => Name;
 
         //IGuildChannel

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

@@ -49,8 +49,25 @@ namespace Discord.Rest
             Update(model);
         }
 
+        /// <summary>
+        ///     Gets a user that is able to view this channel from the associate <paramref name="id"/>.
+        /// </summary>
+        /// <param name="id">The snowflake identifier of the user you want to get.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/> containing a <see cref="RestGuildUser"/>.
+        /// </returns>
         public Task<RestGuildUser> GetUserAsync(ulong id, RequestOptions options = null)
             => ChannelHelper.GetUserAsync(this, Guild, Discord, id, options);
+
+        /// <summary>
+        ///     Gets the collection of users that can view this channel.
+        /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     Paged collection of users. Flattening the paginated response into a collection of <see cref="RestGuildUser"/>
+        ///     with <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> is required if you wish to access the users. 
+        /// </returns>
         public IAsyncEnumerable<IReadOnlyCollection<RestGuildUser>> GetUsersAsync(RequestOptions options = null)
             => ChannelHelper.GetUsersAsync(this, Guild, Discord, null, null, options);
 
@@ -128,7 +145,16 @@ namespace Discord.Rest
         /// <inheritdoc />
         public IDisposable EnterTypingState(RequestOptions options = null)
             => ChannelHelper.EnterTypingState(this, Discord, options);
-        
+
+        /// <summary>
+        ///     Creates a webhook for this channel.
+        /// </summary>
+        /// <param name="name">The name you want to give the webhook.</param>
+        /// <param name="avatar">The avatar that you want the webook to have.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/> containing a <see cref="RestWebhook"/>.
+        /// </returns>
         public Task<RestWebhook> CreateWebhookAsync(string name, Stream avatar = null, RequestOptions options = null)
             => ChannelHelper.CreateWebhookAsync(this, Discord, name, avatar, options);
         public Task<RestWebhook> GetWebhookAsync(ulong id, RequestOptions options = null)
@@ -136,6 +162,13 @@ namespace Discord.Rest
         public Task<IReadOnlyCollection<RestWebhook>> GetWebhooksAsync(RequestOptions options = null)
             => ChannelHelper.GetWebhooksAsync(this, Discord, options);
 
+        /// <summary>
+        ///     Gets the parent category of this channel.
+        /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/> containing an <see cref="ICategoryChannel"/>.
+        /// </returns>
         public Task<ICategoryChannel> GetCategoryAsync(RequestOptions options = null)
             => ChannelHelper.GetCategoryAsync(this, Discord, options);
 

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

@@ -47,6 +47,13 @@ namespace Discord.Rest
             Update(model);
         }
 
+        /// <summary>
+        ///     Gets the parent category of this channel.
+        /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/> containing an <see cref="ICategoryChannel"/>.
+        /// </returns>
         public Task<ICategoryChannel> GetCategoryAsync(RequestOptions options = null)
             => ChannelHelper.GetCategoryAsync(this, Discord, options);
 

src/Discord.Net.Rest/Entities/Messages/RestMessage.cs

@@ -13,6 +13,9 @@ namespace Discord.Rest
 
         /// <inheritdoc />
         public IMessageChannel Channel { get; }
+        /// <summary>
+        ///     Gets the Author of the message.
+        /// </summary>
         public IUser Author { get; }
         /// <inheritdoc />
         public MessageSource Source { get; }
@@ -28,12 +31,21 @@ namespace Discord.Rest
         public virtual bool IsPinned => false;
         /// <inheritdoc />
         public virtual DateTimeOffset? EditedTimestamp => null;
+        /// <summary>
+        ///     Gets a collection of the <see cref="Attachment"/>'s on the message.
+        /// </summary>
         public virtual IReadOnlyCollection<Attachment> Attachments => ImmutableArray.Create<Attachment>();
+        /// <summary>
+        ///     Gets a collection of the <see cref="Embed"/>'s on the message.
+        /// </summary>
         public virtual IReadOnlyCollection<Embed> Embeds => ImmutableArray.Create<Embed>();
         /// <inheritdoc />
         public virtual IReadOnlyCollection<ulong> MentionedChannelIds => ImmutableArray.Create<ulong>();
         /// <inheritdoc />
         public virtual IReadOnlyCollection<ulong> MentionedRoleIds => ImmutableArray.Create<ulong>();
+        /// <summary>
+        ///     Gets a collection of the mentioned users in the message.
+        /// </summary>
         public virtual IReadOnlyCollection<RestUser> MentionedUsers => ImmutableArray.Create<RestUser>();
         /// <inheritdoc />
         public virtual IReadOnlyCollection<ITag> Tags => ImmutableArray.Create<ITag>();
@@ -74,6 +86,12 @@ namespace Discord.Rest
         public Task DeleteAsync(RequestOptions options = null)
             => MessageHelper.DeleteAsync(this, Discord, options);
 
+        /// <summary>
+        ///     Gets the <see cref="Content"/> of the message.
+        /// </summary>
+        /// <returns>
+        ///     A string that is the <see cref="Content"/> of the message.
+        /// </returns>
         public override string ToString() => Content;
 
         /// <inheritdoc />

src/Discord.Net.Rest/Entities/Roles/RestRole.cs

@@ -26,6 +26,9 @@ namespace Discord.Rest
 
         /// <inheritdoc />
         public DateTimeOffset CreatedAt => SnowflakeUtils.FromSnowflake(Id);
+        /// <summary>
+        ///     Gets if this role is the @everyone role of the guild or not.
+        /// </summary>
         public bool IsEveryone => Id == Guild.Id;
         /// <inheritdoc />
         public string Mention => IsEveryone ? "@everyone" : MentionUtils.MentionRole(Id);
@@ -65,6 +68,12 @@ namespace Discord.Rest
         /// <inheritdoc />
         public int CompareTo(IRole role) => RoleUtils.Compare(this, role);
 
+        /// <summary>
+        ///     Gets the name of the role.
+        /// </summary>
+        /// <returns>
+        ///     A string that is the name of the role.
+        /// </returns>
         public override string ToString() => Name;
         private string DebuggerDisplay => $"{Name} ({Id})";
 

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

@@ -76,6 +76,12 @@ namespace Discord.Rest
         public string GetDefaultAvatarUrl()
             => CDN.GetDefaultUserAvatarUrl(DiscriminatorValue);
 
+        /// <summary>
+        ///     Gets the Username#Descriminator of the user.
+        /// </summary>
+        /// <returns>
+        ///     A string that is the 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

@@ -19,6 +19,9 @@ namespace Discord.WebSocket
     {
         private readonly MessageCache _messages;
 
+        /// <summary>
+        ///     Gets the recipient of the channel.
+        /// </summary>
         public SocketUser Recipient { get; }
 
         /// <inheritdoc />
@@ -52,6 +55,14 @@ namespace Discord.WebSocket
         /// <inheritdoc />
         public SocketMessage GetCachedMessage(ulong id)
             => _messages?.Get(id);
+        /// <summary>
+        ///     Gets the message associated with the given <paramref name="id"/>.
+        /// </summary>
+        /// <param name="id">TThe ID of the message.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     The message gotten from either the cache or the download, or <c>null</c> if none is found.
+        /// </returns>
         public async Task<IMessage> GetMessageAsync(ulong id, RequestOptions options = null)
         {
             IMessage msg = _messages?.Get(id);
@@ -59,6 +70,16 @@ namespace Discord.WebSocket
                 msg = await ChannelHelper.GetMessageAsync(this, Discord, id, options).ConfigureAwait(false);
             return msg;
         }
+
+        /// <summary>
+        ///     Gets the last N messages from this channel.
+        /// </summary>
+        /// <param name="limit">The number of messages to get.</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(int limit = DiscordConfig.MaxMessagesPerBatch, RequestOptions options = null)
             => SocketChannelHelper.GetMessagesAsync(this, Discord, _messages, null, Direction.Before, limit, CacheMode.AllowDownload, options);
         public IAsyncEnumerable<IReadOnlyCollection<IMessage>> GetMessagesAsync(ulong fromMessageId, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch, RequestOptions options = null)
@@ -90,9 +111,10 @@ namespace Discord.WebSocket
         /// <exception cref="ArgumentOutOfRangeException">Message content is too long, length must be less or equal to <see cref="DiscordConfig.MaxMessageSize"/>.</exception>
         public Task<RestUserMessage> SendFileAsync(Stream stream, string filename, string text, bool isTTS = false, Embed embed = null, RequestOptions options = null)
             => ChannelHelper.SendFileAsync(this, Discord, stream, filename, text, isTTS, embed, options);
-
+        /// <inheritdoc />
         public Task DeleteMessageAsync(ulong messageId, RequestOptions options = null)
             => ChannelHelper.DeleteMessageAsync(this, messageId, Discord, options);
+        /// <inheritdoc />
         public Task DeleteMessageAsync(IMessage message, RequestOptions options = null)
             => ChannelHelper.DeleteMessageAsync(this, message.Id, Discord, options);
 
@@ -109,6 +131,13 @@ namespace Discord.WebSocket
             => _messages?.Remove(id);
 
         //Users
+        /// <summary>
+        ///     Gets a user in this channel from the provided <paramref name="id"/>.
+        /// </summary>
+        /// <param name="id">The snowflake identifier of the user.</param>
+        /// <returns>
+        ///     A <see cref="SocketUser"/> object that is a recipient of this channel; otherwise <c>null</c>.
+        /// </returns>
         public new SocketUser GetUser(ulong id)
         {
             if (id == Recipient.Id)
@@ -165,8 +194,10 @@ namespace Discord.WebSocket
         /// <inheritdoc />
         async Task<IReadOnlyCollection<IMessage>> IMessageChannel.GetPinnedMessagesAsync(RequestOptions options)
             => await GetPinnedMessagesAsync(options).ConfigureAwait(false);
+        /// <inheritdoc />
         async Task<IUserMessage> IMessageChannel.SendFileAsync(string filePath, string text, bool isTTS, Embed embed, RequestOptions options)
             => await SendFileAsync(filePath, text, isTTS, embed, options).ConfigureAwait(false);
+        /// <inheritdoc />
         async Task<IUserMessage> IMessageChannel.SendFileAsync(Stream stream, string filename, string text, bool isTTS, Embed embed, RequestOptions options)
             => await SendFileAsync(stream, filename, text, isTTS, embed, options).ConfigureAwait(false);
         /// <inheritdoc />

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

@@ -141,6 +141,14 @@ namespace Discord.WebSocket
             await ChannelHelper.AddPermissionOverwriteAsync(this, Discord, role, perms, options).ConfigureAwait(false);
             _overwrites = _overwrites.Add(new Overwrite(role.Id, PermissionTarget.Role, new OverwritePermissions(perms.AllowValue, perms.DenyValue)));
         }
+        /// <summary>
+        ///     Removes an overwrite permission for the specified <paramref name="user"/>.
+        /// </summary>
+        /// <param name="user">The user you want to remove the overwrite permission from.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/>.
+        /// </returns>
         public async Task RemovePermissionOverwriteAsync(IUser user, RequestOptions options = null)
         {
             await ChannelHelper.RemovePermissionOverwriteAsync(this, Discord, user, options).ConfigureAwait(false);
@@ -154,6 +162,14 @@ namespace Discord.WebSocket
                 }
             }
         }
+        /// <summary>
+        ///     Removes an overwrite permission for the specified <paramref name="role"/>.
+        /// </summary>
+        /// <param name="role">The role you want the overwrite permissions to be removed from.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/>.
+        /// </returns>
         public async Task RemovePermissionOverwriteAsync(IRole role, RequestOptions options = null)
         {
             await ChannelHelper.RemovePermissionOverwriteAsync(this, Discord, role, options).ConfigureAwait(false);
@@ -168,8 +184,28 @@ namespace Discord.WebSocket
             }
         }
 
+        /// <summary>
+        ///     Gets the invites for this channel.
+        /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/> containing an <see cref="IReadOnlyCollection{RestInviteMetaData}"/>.
+        ///     <see cref="RestInviteMetadata"/> contains information such as, the number of times the invite has
+        ///     been used, who created the invite, and when the invite was created.
+        /// </returns>
         public async Task<IReadOnlyCollection<RestInviteMetadata>> GetInvitesAsync(RequestOptions options = null)
             => await ChannelHelper.GetInvitesAsync(this, Discord, options).ConfigureAwait(false);
+        /// <summary>
+        ///     Creates an invite for this channel.
+        /// </summary>
+        /// <param name="maxAge">The number of seconds that you want the invite to be valid for.</param>
+        /// <param name="maxUses">The number of times this invite can be used before it expires.</param>
+        /// <param name="isTemporary">Whether or not the invite grants temporary membership.</param>
+        /// <param name="isUnique">Whether to try reuse a similar invite or not.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/> containing a <see cref="RestInviteMetadata"/>.
+        /// </returns>
         public async Task<RestInviteMetadata> CreateInviteAsync(int? maxAge = 86400, int? maxUses = null, bool isTemporary = false, bool isUnique = false, RequestOptions options = null)
             => await ChannelHelper.CreateInviteAsync(this, Discord, maxAge, maxUses, isTemporary, isUnique, options).ConfigureAwait(false);