docs: 2020 April Documentation Maintenance (discord-net#1484)

* 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>

docs/docfx.json

@@ -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"

docs/faq/basics/basic-operations.md

@@ -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?"
 

docs/guides/commands/intro.md

@@ -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.
 

docs/guides/commands/namedarguments.md

@@ -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

docs/guides/toc.yml

@@ -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

src/Discord.Net.Commands/CommandService.cs

@@ -36,7 +36,7 @@ public class CommandService : IDisposable
         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

src/Discord.Net.Core/Entities/Channels/INestedChannel.cs

@@ -40,8 +40,8 @@ public interface INestedChannel : IGuildChannel
         ///     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 @@ public interface INestedChannel : IGuildChannel
         ///     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;

src/Discord.Net.Core/Entities/Channels/ITextChannel.cs

@@ -30,7 +30,7 @@ public interface ITextChannel : IMessageChannel, IMentionable, INestedChannel
         ///     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 @@ public interface ITextChannel : IMessageChannel, IMentionable, INestedChannel
         ///     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);

src/Discord.Net.Core/Entities/Guilds/IGuild.cs

@@ -510,7 +510,7 @@ public interface IGuild : IDeletable, ISnowflakeEntity
         ///     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>

src/Discord.Net.Core/Entities/Messages/IMessage.cs

@@ -161,7 +161,7 @@ public interface IMessage : ISnowflakeEntity, IDeletable
         ///     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 @@ public interface IMessage : ISnowflakeEntity, IDeletable
         ///     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 @@ public interface IMessage : ISnowflakeEntity, IDeletable
         ///     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 @@ public interface IMessage : ISnowflakeEntity, IDeletable
         /// <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 @@ public interface IMessage : ISnowflakeEntity, IDeletable
         /// <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);
     }

src/Discord.Net.Core/Entities/Messages/IUserMessage.cs

@@ -17,7 +17,7 @@ public interface IUserMessage : IMessage
         ///     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>

src/Discord.Net.Core/Entities/Users/IGuildUser.cs

@@ -72,8 +72,8 @@ public interface IGuildUser : IUser, IVoiceState
         ///     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");

src/Discord.Net.Core/Entities/Users/IUser.cs

@@ -21,8 +21,8 @@ public interface IUser : ISnowflakeEntity, IMentionable, IPresence
         ///     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 @@ public interface IUser : ISnowflakeEntity, IMentionable, IPresence
         ///     </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>

src/Discord.Net.Core/Extensions/MessageExtensions.cs

@@ -39,7 +39,7 @@ public static string GetJumpUrl(this IMessage msg)
         /// <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 @@ public static async Task AddReactionsAsync(this IUserMessage msg, IEmote[] react
         /// </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 @@ public static async Task AddReactionsAsync(this IUserMessage msg, IEmote[] react
         /// <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)
         {

src/Discord.Net.Core/Extensions/UserExtensions.cs

@@ -44,8 +44,8 @@ public static class UserExtensions
         ///     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());

src/Discord.Net.Core/IDiscordClient.cs

@@ -270,7 +270,7 @@ public interface IDiscordClient : IDisposable
         /// </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);

src/Discord.Net.Core/RequestOptions.cs

@@ -49,8 +49,7 @@ public class RequestOptions
 		///		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.

src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/ChannelCreateAuditLogData.cs

@@ -78,7 +78,7 @@ internal static ChannelCreateAuditLogData Create(BaseDiscordClient discord, Mode
         ///     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 @@ internal static ChannelCreateAuditLogData Create(BaseDiscordClient discord, Mode
         ///     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>