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

4
docs/docfx.json
View File

@@ -9,7 +9,7 @@
"dest": "api",
"filter": "filterConfig.yml",
"properties": {
"TargetFramework": "netstandard1.3"
"TargetFramework": "netstandard2.0"
}
}],
"build": {
@@ -51,7 +51,7 @@
"overwrite": "_overwrites/**/**.md",
"globalMetadata": {
"_appTitle": "Discord.Net Documentation",
"_appFooter": "Discord.Net (c) 2015-2019 2.1.1",
"_appFooter": "Discord.Net (c) 2015-2020 2.2.0",
"_enableSearch": true,
"_appLogoPath": "marketing/logo/SVG/Logomark Purple.svg",
"_appFaviconPath": "favicon.ico"

2
docs/faq/basics/basic-operations.md
View File

@@ -88,7 +88,7 @@ implement [IEmote] and are valid options.
***
[AddReactionAsync]: xref:Discord.IUserMessage.AddReactionAsync*
[AddReactionAsync]: xref:Discord.IMessage.AddReactionAsync*
## What is a "preemptive rate limit?"

8
docs/guides/commands/intro.md
View File

@@ -71,11 +71,11 @@ By now, your module should look like this:
> [!WARNING]
> **Avoid using long-running code** in your modules wherever possible.
> You should **not** be implementing very much logic into your
> modules, instead, outsource to a service for that.
> Long-running code, by default, within a command module
> can cause gateway thread to be blocked; therefore, interrupting
> the bot's connection to Discord.
>
> If you are unfamiliar with Inversion of Control, it is recommended
> to read the MSDN article on [IoC] and [Dependency Injection].
> You may read more about it in @FAQ.Commands.General .
The next step to creating commands is actually creating the commands.

79
docs/guides/commands/namedarguments.md Normal file
View File

@@ -0,0 +1,79 @@
---
uid: Guides.Commands.NamedArguments
title: Named Arguments
---
# Named Arguments
By default, arguments for commands are parsed positionally, meaning
that the order matters. But sometimes you may want to define a command
with many optional parameters, and it'd be easier for end-users
to only specify what they want to set, instead of needing them
to specify everything by hand.
## Setting up Named Arguments
In order to be able to specify different arguments by name, you have
to create a new class that contains all of the optional values that
the command will use, and apply an instance of
[NamedArgumentTypeAttribute] on it.
### Example - Creating a Named Arguments Type
```cs
[NamedArgumentType]
public class NamableArguments
{
public string First { get; set; }
public string Second { get; set; }
public string Third { get; set; }
public string Fourth { get; set; }
}
```
## Usage in a Command
The command where you want to use these values can be declared like so:
```cs
[Command("act")]
public async Task Act(int requiredArg, NamableArguments namedArgs)
```
The command can now be invoked as
`.act 42 first: Hello fourth: "A string with spaces must be wrapped in quotes" second: World`.
A TypeReader for the named arguments container type is
automatically registered.
It's important that any other arguments that would be required
are placed before the container type.
> [!IMPORTANT]
> A single command can have only __one__ parameter of a
> type annotated with [NamedArgumentTypeAttribute], and it
> **MUST** be the last parameter in the list.
> A command parameter of such an annotated type
> is automatically treated as if that parameter
> has [RemainderAttribute](xref:Discord.Commands.RemainderAttribute)
> applied.
## Complex Types
The TypeReader for Named Argument Types will look for a TypeReader
of every property type, meaning any other command parameter type
will work just the same.
You can also read multiple values into a single property
by making that property an `IEnumerable<T>`. So for example, if your
Named Argument Type has the following field,
```cs
public IEnumerable<int> Numbers { get; set; }
```
then the command can be invoked as
`.cmd numbers: "1, 2, 4, 8, 16, 32"`
## Additional Notes
The use of [`[OverrideTypeReader]`](xref:Discord.Commands.OverrideTypeReaderAttribute)
is also supported on the properties of a Named Argument Type.
[NamedArgumentTypeAttribute]: xref:Discord.Commands.NamedArgumentTypeAttribute

2
docs/guides/toc.yml
View File

@@ -27,6 +27,8 @@
topicUid: Guides.Commands.Intro
- name: TypeReaders
topicUid: Guides.Commands.TypeReaders
- name: Named Arguments
topicUid: Guides.Commands.NamedArguments
- name: Preconditions
topicUid: Guides.Commands.Preconditions
- name: Dependency Injection

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)