docs: 2020 April Documentation Maintenance (#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