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

docs: 2020 April Documentation Maintenance (#1484)

Browse Source 
* Add doc page for Named Arguments

* Implement minor stylistic changes

* Update docfx.json to support NS2.0

Signed-off-by: Still Hsu <5843208+Still34@users.noreply.github.com>

* Fix broken xref in basic-operations

* Fix broken crefs

* Fix wordings in named argument

* Fix misleading warning about long-running code

* Fix misleading CommandService summary

Signed-off-by: Still Hsu <5843208+Still34@users.noreply.github.com>

* Update copyright year and version

Signed-off-by: Still Hsu <5843208+Still34@users.noreply.github.com>

* Escape example captions

* Add warning regarding FlattenAsync for GetReactionUsersAsync

* Fix a minor grammar mistake

Co-authored-by: Joe4evr <jii.geugten@gmail.com>
This commit is contained in:
Still Hsu
2020-04-22 14:04:10 +08:00
committed by GitHub
parent 1f01a2d1fa
commit 106f346ddb
21 changed files with 139 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
src/Discord.Net.Commands/CommandService.cs
View File

@@ -36,7 +36,7 @@ namespace Discord.Commands
internal readonly AsyncEvent<Func<LogMessage, Task>> _logEvent = new AsyncEvent<Func<LogMessage, Task>>();
/// <summary>
/// Occurs when a command is successfully executed without any error.
/// Occurs when a command is executed.
/// </summary>
/// <remarks>
/// This event is fired when a command has been executed, successfully or not. When a command fails to

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

@@ -40,8 +40,8 @@ namespace Discord
/// Creates a new invite to this channel.
/// </summary>
/// <example>
/// The following example creates a new invite to this channel; the invite lasts for 12 hours and can only
/// be used 3 times throughout its lifespan.
/// <para>The following example creates a new invite to this channel; the invite lasts for 12 hours and can only
/// be used 3 times throughout its lifespan.</para>
/// <code language="cs">
/// await guildChannel.CreateInviteAsync(maxAge: 43200, maxUses: 3);
/// </code>
@@ -60,8 +60,8 @@ namespace Discord
/// Gets a collection of all invites to this channel.
/// </summary>B
/// <example>
/// The following example gets all of the invites that have been created in this channel and selects the
/// most used invite.
/// <para>The following example gets all of the invites that have been created in this channel and selects the
/// most used invite.</para>
/// <code language="cs">
/// var invites = await channel.GetInvitesAsync();
/// if (invites.Count == 0) return;

4
src/Discord.Net.Core/Entities/Channels/ITextChannel.cs
View File

@@ -30,7 +30,7 @@ namespace Discord
/// Gets the current slow-mode delay for this channel.
/// </summary>
/// <returns>
/// An <see cref="Int32"/> representing the time in seconds required before the user can send another
/// An <see cref="int"/> representing the time in seconds required before the user can send another
/// message; <c>0</c> if disabled.
/// </returns>
int SlowModeInterval { get; }
@@ -39,7 +39,7 @@ namespace Discord
/// Bulk-deletes multiple messages.
/// </summary>
/// <example>
/// The following example gets 250 messages from the channel and deletes them.
/// <para>The following example gets 250 messages from the channel and deletes them.</para>
/// <code language="cs">
/// var messages = await textChannel.GetMessagesAsync(250).FlattenAsync();
/// await textChannel.DeleteMessagesAsync(messages);

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

@@ -510,7 +510,7 @@ namespace Discord
/// Creates a new text channel in this guild.
/// </summary>
/// <example>
/// The following example creates a new text channel under an existing category named <c>Wumpus</c> with a set topic.
/// <para>The following example creates a new text channel under an existing category named <c>Wumpus</c> with a set topic.</para>
/// <code language="cs" region="CreateTextChannelAsync"
/// source="..\..\..\Discord.Net.Examples\Core\Entities\Guilds\IGuild.Examples.cs"/>
/// </example>

29
src/Discord.Net.Core/Entities/Messages/IMessage.cs
View File

@@ -161,7 +161,7 @@ namespace Discord
/// Adds a reaction to this message.
/// </summary>
/// <example>
/// The following example adds the reaction, <c>💕</c>, to the message.
/// <para>The following example adds the reaction, <c>💕</c>, to the message.</para>
/// <code language="cs">
/// await msg.AddReactionAsync(new Emoji("\U0001f495"));
/// </code>
@@ -177,7 +177,7 @@ namespace Discord
/// Removes a reaction from message.
/// </summary>
/// <example>
/// The following example removes the reaction, <c>💕</c>, added by the message author from the message.
/// <para>The following example removes the reaction, <c>💕</c>, added by the message author from the message.</para>
/// <code language="cs">
/// await msg.RemoveReactionAsync(new Emoji("\U0001f495"), msg.Author);
/// </code>
@@ -194,7 +194,7 @@ namespace Discord
/// Removes a reaction from message.
/// </summary>
/// <example>
/// The following example removes the reaction, <c>💕</c>, added by the user with ID 84291986575613952 from the message.
/// <para>The following example removes the reaction, <c>💕</c>, added by the user with ID 84291986575613952 from the message.</para>
/// <code language="cs">
/// await msg.RemoveReactionAsync(new Emoji("\U0001f495"), 84291986575613952);
/// </code>
@@ -219,8 +219,25 @@ namespace Discord
/// <summary>
/// Gets all users that reacted to a message with a given emote.
/// </summary>
/// <remarks>
/// <note type="important">
/// The returned collection is an asynchronous enumerable object; one must call
/// <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> to access the users as a
/// collection.
/// </note>
/// <note type="warning">
/// Do not fetch too many users at once! This may cause unwanted preemptive rate limit or even actual
/// rate limit, causing your bot to freeze!
/// </note>
/// This method will attempt to fetch the number of reactions specified under <paramref name="limit"/>.
/// The library will attempt to split up the requests according to your <paramref name="limit"/> and
/// <see cref="DiscordConfig.MaxUserReactionsPerBatch"/>. In other words, should the user request 500 reactions,
/// and the <see cref="Discord.DiscordConfig.MaxUserReactionsPerBatch"/> constant is <c>100</c>, the request will
/// be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need
/// of flattening.
/// </remarks>
/// <example>
/// The following example gets the users that have reacted with the emoji <c>💕</c> to the message.
/// <para>The following example gets the users that have reacted with the emoji <c>💕</c> to the message.</para>
/// <code language="cs">
/// var emoji = new Emoji("\U0001f495");
/// var reactedUsers = await message.GetReactionUsersAsync(emoji, 100).FlattenAsync();
@@ -230,9 +247,7 @@ namespace Discord
/// <param name="limit">The number of users to request.</param>
/// <param name="options">The options to be used when sending the request.</param>
/// <returns>
/// A paged collection containing a read-only collection of users that has reacted to this message.
/// 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>> GetReactionUsersAsync(IEmote emoji, int limit, RequestOptions options = null);
}

2
src/Discord.Net.Core/Entities/Messages/IUserMessage.cs
View File

@@ -17,7 +17,7 @@ namespace Discord
/// method and what properties are available, please refer to <see cref="MessageProperties"/>.
/// </remarks>
/// <example>
/// The following example replaces the content of the message with <c>Hello World!</c>.
/// <para>The following example replaces the content of the message with <c>Hello World!</c>.</para>
/// <code language="cs">
/// await msg.ModifyAsync(x =&gt; x.Content = "Hello World!");
/// </code>

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

@@ -72,8 +72,8 @@ namespace Discord
/// Gets the level permissions granted to this user to a given channel.
/// </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(string, string, bool, Embed, RequestOptions, bool)"/>.
/// <para>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(string, string, bool, Embed, RequestOptions, bool)"/>.</para>
/// <code language="cs">
/// if (currentUser?.GetPermissions(targetChannel)?.AttachFiles)
/// await targetChannel.SendFileAsync("fortnite.png");

8
src/Discord.Net.Core/Entities/Users/IUser.cs
View File

@@ -21,8 +21,8 @@ namespace Discord
/// example).
/// </remarks>
/// <example>
/// The following example attempts to retrieve the user's current avatar and send it to a channel; if one is
/// not set, a default avatar for this user will be returned instead.
/// <para>The following example attempts to retrieve the user's current avatar and send it to a channel; if one is
/// not set, a default avatar for this user will be returned instead.</para>
/// <code language="cs" region="GetAvatarUrl"
/// source="..\..\..\Discord.Net.Examples\Core\Entities\Users\IUser.Examples.cs"/>
/// </example>
@@ -90,8 +90,8 @@ namespace Discord
/// </note>
/// </remarks>
/// <example>
/// The following example attempts to send a direct message to the target user and logs the incident should
/// it fail.
/// <para>The following example attempts to send a direct message to the target user and logs the incident should
/// it fail.</para>
/// <code region="GetOrCreateDMChannelAsync" language="cs"
/// source="../../../Discord.Net.Examples/Core/Entities/Users/IUser.Examples.cs"/>
/// </example>

6
src/Discord.Net.Core/Extensions/MessageExtensions.cs
View File

@@ -39,7 +39,7 @@ namespace Discord
/// <returns>
/// A task that represents the asynchronous operation for adding a reaction to this message.
/// </returns>
/// <seealso cref="IUserMessage.AddReactionAsync(IEmote, RequestOptions)"/>
/// <seealso cref="IMessage.AddReactionAsync(IEmote, RequestOptions)"/>
/// <seealso cref="IEmote"/>
public static async Task AddReactionsAsync(this IUserMessage msg, IEmote[] reactions, RequestOptions options = null)
{
@@ -51,7 +51,7 @@ namespace Discord
/// </summary>
/// <remarks>
/// This method does not bulk remove reactions! If you want to clear reactions from a message,
/// <see cref="IUserMessage.RemoveAllReactionsAsync(RequestOptions)"/>
/// <see cref="IMessage.RemoveAllReactionsAsync(RequestOptions)"/>
/// </remarks>
/// <example>
/// <code language="cs">
@@ -64,7 +64,7 @@ namespace Discord
/// <returns>
/// A task that represents the asynchronous operation for removing a reaction to this message.
/// </returns>
/// <seealso cref="IUserMessage.RemoveReactionAsync(IEmote, IUser, RequestOptions)"/>
/// <seealso cref="IMessage.RemoveReactionAsync(IEmote, IUser, RequestOptions)"/>
/// <seealso cref="IEmote"/>
public static async Task RemoveReactionsAsync(this IUserMessage msg, IUser user, IEmote[] reactions, RequestOptions options = null)
{

4
src/Discord.Net.Core/Extensions/UserExtensions.cs
View File

@@ -44,8 +44,8 @@ namespace Discord
/// Sends a file to this message channel with an optional caption.
/// </summary>
/// <example>
/// The following example uploads a streamed image that will be called <c>b1nzy.jpg</c> embedded inside a
/// rich embed to the channel.
/// <para>The following example uploads a streamed image that will be called <c>b1nzy.jpg</c> embedded inside a
/// rich embed to the channel.</para>
/// <code language="cs">
/// await channel.SendFileAsync(b1nzyStream, "b1nzy.jpg",
/// embed: new EmbedBuilder {ImageUrl = "attachment://b1nzy.jpg"}.Build());

2
src/Discord.Net.Core/IDiscordClient.cs
View File

@@ -270,7 +270,7 @@ namespace Discord
/// </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 an <see cref="Int32"/>
/// A task that represents the asynchronous get operation. The task result contains an <see cref="int"/>
/// that represents the number of shards that should be used with this account.
/// </returns>
Task<int> GetRecommendedShardCountAsync(RequestOptions options = null);

3
src/Discord.Net.Core/RequestOptions.cs
View File

@@ -49,8 +49,7 @@ namespace Discord
/// clock for rate-limiting. Defaults to <c>true</c>.
/// </summary>
/// <remarks>
/// This property can also be set in <see cref="DiscordConfig">.
///
/// This property can also be set in <see cref="DiscordConfig"/>.
/// On a per-request basis, the system clock should only be disabled
/// when millisecond precision is especially important, and the
/// hosting system is known to have a desynced clock.

4
src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelCreateAuditLogData.cs
View File

@@ -78,7 +78,7 @@ namespace Discord.Rest
/// Gets the current slow-mode delay of the created channel.
/// </summary>
/// <returns>
/// An <see cref="Int32"/> representing the time in seconds required before the user can send another
/// An <see cref="int"/> representing the time in seconds required before the user can send another
/// message; <c>0</c> if disabled.
/// <c>null</c> if this is not mentioned in this entry.
/// </returns>
@@ -95,7 +95,7 @@ namespace Discord.Rest
/// Gets the bit-rate that the clients in the created voice channel are requested to use.
/// </summary>
/// <returns>
/// An <see cref="Int32"/> representing the bit-rate (bps) that the created voice channel defines and requests the
/// An <see cref="int"/> representing the bit-rate (bps) that the created voice channel defines and requests the
/// client(s) to use.
/// <c>null</c> if this is not mentioned in this entry.
/// </returns>

4
src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelDeleteAuditLogData.cs
View File

@@ -71,7 +71,7 @@ namespace Discord.Rest
/// Gets the slow-mode delay of the deleted channel.
/// </summary>
/// <returns>
/// An <see cref="Int32"/> representing the time in seconds required before the user can send another
/// An <see cref="int"/> representing the time in seconds required before the user can send another
/// message; <c>0</c> if disabled.
/// <c>null</c> if this is not mentioned in this entry.
/// </returns>
@@ -88,7 +88,7 @@ namespace Discord.Rest
/// Gets the bit-rate of this channel if applicable.
/// </summary>
/// <returns>
/// An <see cref="Int32"/> representing the bit-rate set of the voice channel.
/// An <see cref="int"/> representing the bit-rate set of the voice channel.
/// <c>null</c> if this is not mentioned in this entry.
/// </returns>
public int? Bitrate { get; }

4
src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelInfo.cs
View File

@@ -32,7 +32,7 @@ namespace Discord.Rest
/// Gets the current slow-mode delay of this channel.
/// </summary>
/// <returns>
/// An <see cref="Int32"/> representing the time in seconds required before the user can send another
/// An <see cref="int"/> representing the time in seconds required before the user can send another
/// message; <c>0</c> if disabled.
/// <c>null</c> if this is not mentioned in this entry.
/// </returns>
@@ -49,7 +49,7 @@ namespace Discord.Rest
/// Gets the bit-rate of this channel if applicable.
/// </summary>
/// <returns>
/// An <see cref="Int32"/> representing the bit-rate set for the voice channel;
/// An <see cref="int"/> representing the bit-rate set for the voice channel;
/// <c>null</c> if this is not mentioned in this entry.
/// </returns>
public int? Bitrate { get; }

2
src/Discord.Net.Webhook/DiscordWebhookClient.cs
View File

@@ -85,7 +85,7 @@ namespace Discord.Webhook
}
private static API.DiscordRestApiClient CreateApiClient(DiscordRestConfig config)
=> new API.DiscordRestApiClient(config.RestClientProvider, DiscordRestConfig.UserAgent);
/// <summary> Sends a message using to the channel for this webhook. </summary>
/// <summary> Sends a message to the channel for this webhook. </summary>
/// <returns> Returns the ID of the created message. </returns>
public Task<ulong> SendMessageAsync(string text = null, bool isTTS = false, IEnumerable<Embed> embeds = null,
string username = null, string avatarUrl = null, RequestOptions options = null)