github/Discord.Net
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: September 2019 Documentation Update (#1379)

Browse Source 
* docs: adjust wording of ActivityType.Watching enum

Adjusts the xmldoc summary wording of the ActivityType.Watching enum to
fix a wording issue.

* Add D.NET Logo to Open Graph meta tags

* Update DescriptionGenerator
...And update color to suit the logo better

* Disable smooth scrolling due to user complaints

* Remove unnecessary spacing in sideaffix

* Update footer version

* Remove featherlight plugin

As it is unnecessary and can break image tags

* Adjust wordings regarding safe-handling of secrets

* Fix formatting for first bot token sample

* Add badges to homepage

* Minor wording fixes on terminal

* Update to higher quality PNG

* Add Discord.Net.Example in sln for build validation

* Clarify all instances of IAsnycEnumerable

* Clarify overridden props in SocketNewsChannel

* Add returns and params docs for SyncPermissionsAsync

* Remove/fix invalid XMLdoc strings

* Remove AppVeyor and add GitHub badge
This commit is contained in:
Still Hsu
2019-09-23 07:06:57 +08:00
committed by Christopher F
parent 7b9029dd91
commit fd3810e9fe
23 changed files with 165 additions and 127 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
src/Discord.Net.Core/Entities/Activities/ActivityType.cs
View File

@@ -18,7 +18,7 @@ namespace Discord
/// </summary>
Listening = 2,
/// <summary>
/// The user is watching a media.
/// The user is watching some form of media.
/// </summary>
Watching = 3
}

7
src/Discord.Net.Core/Entities/Channels/Direction.cs
View File

@@ -1,14 +1,15 @@
namespace Discord
{
/// <summary>
/// Specifies the direction of where message(s) should be retrieved from.
/// Specifies the direction of where message(s) should be retrieved from.
/// </summary>
/// <remarks>
/// This enum is used to specify the direction for retrieving messages.
/// <note type="important">
/// At the time of writing, <see cref="Around"/> is not yet implemented into
/// <see cref="IMessageChannel.GetMessagesAsync"/>. Attempting to use the method with <see cref="Around"/>
/// as its direction will throw a <see cref="System.NotImplementedException"/>.
/// <see cref="IMessageChannel.GetMessagesAsync(int, CacheMode, RequestOptions)"/>.
/// Attempting to use the method with <see cref="Around"/> will throw
/// a <see cref="System.NotImplementedException"/>.
/// </note>
/// </remarks>
public enum Direction

18
src/Discord.Net.Core/Entities/Channels/IChannel.cs
View File

@@ -17,14 +17,24 @@ namespace Discord
string Name { get; }
/// <summary>
/// Gets a collection of all users in this channel.
/// Gets a collection of users that are able to view the channel or are currently in this channel.
/// </summary>
/// <remarks>
/// <note type="important">
/// The returned collection is an asynchronous enumerable object; one must call
/// <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> to access the individual messages as a
/// collection.
/// </note>
/// This method will attempt to fetch all users that is able to view this channel or is currently in this channel.
/// The library will attempt to split up the requests according to and <see cref="DiscordConfig.MaxUsersPerBatch"/>.
/// In other words, if there are 3000 users, and the <see cref="Discord.DiscordConfig.MaxUsersPerBatch"/> constant
/// is <c>1000</c>, the request will be split into 3 individual requests; thus returning 53individual asynchronous
/// responses, hence the need of flattening.
/// </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>
/// A paged collection containing a collection of users that can access this channel. Flattening the
/// paginated response into a collection of users with
/// <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> is required if you wish to access the users.
/// Paged collection of users.
/// </returns>
IAsyncEnumerable<IReadOnlyCollection<IUser>> GetUsersAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);

10
src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs
View File

@@ -132,14 +132,16 @@ namespace Discord
Task AddPermissionOverwriteAsync(IUser user, OverwritePermissions permissions, RequestOptions options = null);
/// <summary>
/// Gets a collection of users that are able to view the channel.
/// Gets a collection of users that are able to view the channel or are currently in this channel.
/// </summary>
/// <remarks>
/// This method follows the same behavior as described in <see cref="IChannel.GetUsersAsync"/>.
/// Please visit its documentation for more details on this method.
/// </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>
/// A paged collection containing a collection of guild users that can access this channel. Flattening the
/// paginated response into a collection of users with
/// <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> is required if you wish to access the users.
/// Paged collection of users.
/// </returns>
new IAsyncEnumerable<IReadOnlyCollection<IGuildUser>> GetUsersAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
/// <summary>

6
src/Discord.Net.Core/Entities/Channels/INestedChannel.cs
View File

@@ -26,10 +26,14 @@ namespace Discord
/// representing the parent of this channel; <c>null</c> if none is set.
/// </returns>
Task<ICategoryChannel> GetCategoryAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
/// <summary>
/// Syncs the permissions of this nested channel with its parent's.
/// </summary>
/// <param name="options">The options to be used when sending the request.</param>
/// <returns>
/// A task that represents the asynchronous operation for syncing channel permissions with its parent's.
/// </returns>
Task SyncPermissionsAsync(RequestOptions options = null);
/// <summary>

4
src/Discord.Net.Core/Entities/Guilds/IGuild.cs
View File

@@ -586,11 +586,11 @@ namespace Discord
/// <remarks>
/// This method requires you have an OAuth2 access token for the user, requested with the guilds.join scope, and that the bot have the MANAGE_INVITES permission in the guild.
/// </remarks>
/// <param name="id">The snowflake identifier of the user.</param>
/// <param name="userId">The snowflake identifier of the user.</param>
/// <param name="accessToken">The OAuth2 access token for the user, requested with the guilds.join scope.</param>
/// <param name="func">The delegate containing the properties to be applied to the user upon being added to the guild.</param>
/// <param name="options">The options to be used when sending the request.</param>
/// <returns>A guild user associated with the specified <paramref name="id" />; <c>null</c> if the user is already in the guild.</returns>
/// <returns>A guild user associated with the specified <paramref name="userId" />; <c>null</c> if the user is already in the guild.</returns>
Task<IGuildUser> AddGuildUserAsync(ulong userId, string accessToken, Action<AddGuildUserProperties> func = null, RequestOptions options = null);
/// <summary>
/// Gets a collection of all users in this guild.

2
src/Discord.Net.Core/Entities/Users/IGuildUser.cs
View File

@@ -73,7 +73,7 @@ namespace Discord
/// </summary>
/// <example>
/// The following example checks if the current user has the ability to send a message with attachment in
/// this channel; if so, uploads a file via <see cref="IMessageChannel.SendFileAsync"/>.
/// this channel; if so, uploads a file via <see cref="IMessageChannel.SendFileAsync(string, string, bool, Embed, RequestOptions, bool)"/>.
/// <code language="cs">
/// if (currentUser?.GetPermissions(targetChannel)?.AttachFiles)
/// await targetChannel.SendFileAsync("fortnite.png");

5
src/Discord.Net.Core/Extensions/AsyncEnumerableExtensions.cs
View File

@@ -5,6 +5,11 @@ using System.Threading.Tasks;
namespace Discord
{
/// <summary> An extension class for squashing <see cref="IAsyncEnumerable{T}"/>. </summary>
/// <remarks>
/// This set of extension methods will squash an <see cref="IAsyncEnumerable{T}"/> into a
/// single <see cref="IEnumerable{T}"/>. This is often associated with requests that has a
/// set limit when requesting.
/// </remarks>
public static class AsyncEnumerableExtensions
{
/// <summary> Flattens the specified pages into one <see cref="IEnumerable{T}"/> asynchronously. </summary>

1
src/Discord.Net.Rest/Entities/Guilds/RestGuild.cs
View File

@@ -294,7 +294,6 @@ namespace Discord.Rest
/// <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

71
src/Discord.Net.WebSocket/Entities/Channels/SocketNewsChannel.cs
View File

@@ -9,6 +9,11 @@ namespace Discord.WebSocket
/// <summary>
/// Represents a WebSocket-based news channel in a guild that has the same properties as a <see cref="SocketTextChannel"/>.
/// </summary>
/// <remarks>
/// <note type="warning">
/// Most of the properties and methods featured may not be supported due to the nature of the channel.
/// </note>
/// </remarks>
[DebuggerDisplay(@"{DebuggerDisplay,nq}")]
public class SocketNewsChannel : SocketTextChannel
{
@@ -22,31 +27,61 @@ namespace Discord.WebSocket
entity.Update(state, model);
return entity;
}
/// <inheritdoc />
/// <remarks>
/// <note type="important">
/// This property is not supported by this type. Attempting to use this property will result in a <see cref="NotSupportedException"/>.
/// </note>
/// </remarks>
public override int SlowModeInterval
{
get { throw new NotSupportedException("News channels do not support Slow Mode."); }
}
=> throw new NotSupportedException("News channels do not support Slow Mode.");
/// <inheritdoc />
/// <remarks>
/// <note type="important">
/// This method is not supported by this type. Attempting to use this method will result in a <see cref="NotSupportedException"/>.
/// </note>
/// </remarks>
public override Task AddPermissionOverwriteAsync(IRole role, OverwritePermissions permissions, RequestOptions options = null)
{
throw new NotSupportedException("News channels do not support Overwrite Permissions.");
}
=> throw new NotSupportedException("News channels do not support Overwrite Permissions.");
/// <inheritdoc />
/// <remarks>
/// <note type="important">
/// This method is not supported by this type. Attempting to use this method will result in a <see cref="NotSupportedException"/>.
/// </note>
/// </remarks>
public override Task AddPermissionOverwriteAsync(IUser user, OverwritePermissions permissions, RequestOptions options = null)
{
throw new NotSupportedException("News channels do not support Overwrite Permissions.");
}
=> throw new NotSupportedException("News channels do not support Overwrite Permissions.");
/// <inheritdoc />
/// <remarks>
/// <note type="important">
/// This property is not supported by this type. Attempting to use this property will result in a <see cref="NotSupportedException"/>.
/// </note>
/// </remarks>
public override IReadOnlyCollection<Overwrite> PermissionOverwrites
=> throw new NotSupportedException("News channels do not support Overwrite Permissions.");
/// <inheritdoc />
/// <remarks>
/// <note type="important">
/// This method is not supported by this type. Attempting to use this method will result in a <see cref="NotSupportedException"/>.
/// </note>
/// </remarks>
public override Task SyncPermissionsAsync(RequestOptions options = null)
{
throw new NotSupportedException("News channels do not support Overwrite Permissions.");
}
=> throw new NotSupportedException("News channels do not support Overwrite Permissions.");
/// <inheritdoc />
/// <remarks>
/// <note type="important">
/// This method is not supported by this type. Attempting to use this method will result in a <see cref="NotSupportedException"/>.
/// </note>
/// </remarks>
public override Task RemovePermissionOverwriteAsync(IRole role, RequestOptions options = null)
{
throw new NotSupportedException("News channels do not support Overwrite Permissions.");
}
=> throw new NotSupportedException("News channels do not support Overwrite Permissions.");
/// <inheritdoc />
/// <remarks>
/// <note type="important">
/// This method is not supported by this type. Attempting to use this method will result in a <see cref="NotSupportedException"/>.
/// </note>
/// </remarks>
public override Task RemovePermissionOverwriteAsync(IUser user, RequestOptions options = null)
{
throw new NotSupportedException("News channels do not support Overwrite Permissions.");
}
=> throw new NotSupportedException("News channels do not support Overwrite Permissions.");
}
}