Merge pull request #1 from CasinoBoyale/Casino-Docs

Added documentation

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

@@ -47,6 +47,14 @@ public override async Task UpdateAsync(RequestOptions options = null)
         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 @@ IAsyncEnumerable<IReadOnlyCollection<IMessage>> IMessageChannel.GetMessagesAsync
         /// <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 @@ public async Task ModifyAsync(Action<GuildChannelProperties> func, RequestOption
         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 @@ public Task DeleteAsync(RequestOptions options = null)
             }
             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 @@ public Task DeleteAsync(RequestOptions options = null)
             }
             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 @@ public async Task RemovePermissionOverwriteAsync(IUser user, RequestOptions opti
                 }
             }
         }
+
+        /// <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 @@ public async Task RemovePermissionOverwriteAsync(IRole role, RequestOptions opti
             }
         }
 
+        /// <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 @@ public async Task ModifyAsync(Action<TextChannelProperties> func, RequestOptions
             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,14 +145,30 @@ public Task TriggerTypingAsync(RequestOptions options = null)
         /// <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)
             => ChannelHelper.GetWebhookAsync(this, Discord, id, options);
         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 @@ public async Task ModifyAsync(Action<VoiceChannelProperties> func, RequestOption
             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 @@ public abstract class RestMessage : RestEntity<ulong>, IMessage, IUpdateable
 
         /// <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 @@ public abstract class RestMessage : RestEntity<ulong>, IMessage, IUpdateable
         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 @@ public async Task UpdateAsync(RequestOptions options = null)
         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 @@ public class RestRole : RestEntity<ulong>, IRole
 
         /// <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 @@ public Task DeleteAsync(RequestOptions options = null)
         /// <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 @@ public string GetAvatarUrl(ImageFormat format = ImageFormat.Auto, ushort size =
         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" : "")})";