feat: some argument page, and full grammar check

Author: MC-XiaoHei

docs/en/create-commands/arguments/arguments.md

@@ -32,47 +32,29 @@ The CommandAPI is very flexible when it comes to registering arguments, and lets
 
 :::tabs
 ===Java
-```java
-// todo {{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:arguments1}}
-```
+<<< @/../reference-code/src/main/java/createcommands/arguments/Arguments.java#registerArgumentsExample
 ===Kotlin
-```kotlin
-// todo {{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:arguments1}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/Arguments.kt#registerArgumentsExample
 ===Kotlin DSL
-```kotlin
-// todo {{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/ExamplesKotlinDSL.kt:arguments1}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/Arguments.kt#registerArgumentsExampleDSL
 :::
 
 :::tabs
 ===Java
-```java
-// todo {{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:arguments2}}
-```
+<<< @/../reference-code/src/main/java/createcommands/arguments/Arguments.java#registerArgumentsVarargExample
 ===Kotlin
-```kotlin
-// todo {{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:arguments2}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/Arguments.kt#registerArgumentsVarargExample
 ===Kotlin DSL
-```kotlin
-// todo {{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/ExamplesKotlinDSL.kt:arguments2}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/Arguments.kt#registerArgumentsVarargExampleDSL
 :::
 
 :::tabs
 ===Java
-```java
-// todo {{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:arguments3}}
-```
+<<< @/../reference-code/src/main/java/createcommands/arguments/Arguments.java#registerArgumentsListExample
 ===Kotlin
-```kotlin
-// todo {{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:arguments3}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/Arguments.kt#registerArgumentsListExample
 ===Kotlin DSL
-```kotlin
-// todo {{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/ExamplesKotlinDSL.kt:arguments3}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/Arguments.kt#registerArgumentsListExampleDSL
 :::
 
 ## Argument Casting
@@ -81,17 +63,11 @@ To access arguments, they have to be casted to the type that the argument repres
 
 :::tabs
 ===Java
-```java
-// todo {{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:arguments4}}
-```
+<<< @/../reference-code/src/main/java/createcommands/arguments/Arguments.java#argumentCastExample
 ===Kotlin
-```kotlin
-// todo {{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:arguments4}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/Arguments.kt#argumentCastExample
 ===Kotlin DSL
-```kotlin
-// todo {{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/ExamplesKotlinDSL.kt:arguments4}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/Arguments.kt#argumentCastExampleDSL
 :::
 
 The type to cast each argument (declared in the `dev.jorel.commandapi.arguments` package) is listed below:

docs/en/create-commands/arguments/command-arguments.md

@@ -108,13 +108,9 @@ This is how these commands are implemented:
 
 :::tabs
 ===Java
-```java
-{{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:commandArguments1}}
-```
+<<< @/../reference-code/src/main/java/createcommands/arguments/CommandArguments.java#getArgExample
 ===Kotlin
-```kotlin
-{{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:commandArguments1}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/CommandArguments.kt#getArgExample
 :::
 
 ::::
@@ -161,7 +157,7 @@ Optional<String> getRawOptional(int index);
 
 ::::tip Example - Access raw arguments by node name and index
 
-To demonstrate how to access raw arguments, we are going to implement the `/mycommand` again, this time with the following syntax:
+To demonstrate how to access raw arguments, we’re going to implement the `/mycommand` again, this time with the following syntax:
 
 ```mccmd
 /mycommand <entities>
@@ -171,13 +167,9 @@ We want to find out which entity selector is being used when the command is exec
 
 :::tabs
 ===Java
-```java
-{{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:commandArguments2}}
-```
+<<< @/../reference-code/src/main/java/createcommands/arguments/CommandArguments.java#getRawExample
 ===Kotlin
-```kotlin
-{{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:commandArguments2}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/CommandArguments.kt#getRawExample
 :::
 
 ::::
@@ -192,7 +184,7 @@ Unsafe arguments provide the ability to access an argument without needing to ca
 String name = (String) args.get("name");
 ```
 
-When using unsafe arguments you can make your code look like this:
+When using unsafe arguments, you can make your code look like this:
 
 ```java
 String name = args.getUnchecked("name");
@@ -202,7 +194,7 @@ Unsafe arguments can also be accessed by their node names and their indices.
 
 ### Access arguments by node name
 
-Unsafe arguments can also be accessed by node name which, again, is the recommended way of doing it.
+Node name can also access unsafe arguments which, again, is the recommended way of doing it.
 
 Use these methods when accessing unsafe arguments by their node name:
 
@@ -236,13 +228,9 @@ Here, we don't actually want to cast the argument, so we use unsafe arguments to
 
 :::tabs
 ===Java
-```java
-{{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:commandArguments3}}
-```
+<<< @/../reference-code/src/main/java/createcommands/arguments/CommandArguments.java#getUncheckedExample
 ===Kotlin
-```kotlin
-{{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:commandArguments3}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/CommandArguments.kt#getUncheckedExample
 :::
 
 ::::
@@ -251,11 +239,12 @@ Here, we don't actually want to cast the argument, so we use unsafe arguments to
 
 :::warning **Developer's Note:**
 
-The following methods cannot be used to access a value returned by a `CustomArgument` as its return type depends on the base argument for it.
+The following methods can’t be used to access a value returned by a `CustomArgument` as its return type depends on the base argument for it.
 
 :::
 
-Lastly, the CommandArguments class offers you a way to access your arguments in a more safe way by using internal casts. Again, methods are offered to access arguments by their
+Lastly, the CommandArguments class offers you a way to access your arguments in a safer way by using internal casts.
+Again, methods are offered to access arguments by their
 index or their node name:
 
 ```java
@@ -296,17 +285,13 @@ T getOptionalByArgument(Argument<T> argumentType);
 However, while safer, this also introduces the need to first initialize your arguments before you can start implementing your command.
 To visualize this, we want to implement the command from [Access arguments by node name and index](#access-arguments-by-index) again, but this time using safe arguments with an argument instance:
 
-::::tip Example - Access safe arguments using an argument instance
+::::tip Example – Access safe arguments using an argument instance
 
 :::tabs
 ===Java
-```java
-{{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:commandArguments4}}
-```
+<<< @/../reference-code/src/main/java/createcommands/arguments/CommandArguments.java#getByArgumentExample
 ===Kotlin
-```kotlin
-{{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:commandArguments4}}
-```
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/CommandArguments.kt#getByArgumentExample
 :::
 
 ::::

docs/en/create-commands/arguments/listed-arguments.md

@@ -8,7 +8,7 @@ authors:
 
 # Listed arguments
 
-Arguments have a setting which determine whether they are present in the [`CommandArguments args`](./command-arguments) that is populated when executing a command.
+Arguments have a setting that determines whether they’re present in the [`CommandArguments args`](./command-arguments) that is populated when executing a command.
 
 By default, the `LiteralArgument` has this setting set to `false`, hence the literal values are _not_ present in the [`CommandArguments args`](command-arguments).
 

docs/en/create-commands/arguments/optional-arguments.md

@@ -7,7 +7,7 @@ authors:
 
 # Optional Arguments
 
-Sometimes, you want to implement a command that has arguments that do not need to be entered. Take a `/sayhi` command for example. You may want to say "Hi" to yourself, or to another player. For that, we want this command syntax:
+Sometimes, you want to implement a command that has arguments that don’t need to be entered. Take a `/sayhi` command for example. You may want to say "Hi" to yourself or to another player. For that, we want this command syntax:
 
 ```mccmd
 /sayhi          - Says "Hi!" to yourself
@@ -30,7 +30,7 @@ For example, say we're registering a command `/sayhi`:
 /sayhi <target> - Says "Hi!" to a target player
 ```
 
-For that, we are going to register a command `/sayhi`. To add optional arguments, we are going to use the `withOptionalArguments(Argument... args)` method:
+For that, we’re going to register a command `/sayhi`. To add optional arguments, we’re going to use the `withOptionalArguments(Argument... args)` method:
 
 :::tabs
 ===Java
@@ -48,7 +48,7 @@ For that, we are going to register a command `/sayhi`. To add optional arguments
 :::
 
 
-This gives us the ability to run both `/sayhi` and `/sayhi <target>` with the same command name "sayhi", but have different results based on the arguments used.
+This allows us to run both `/sayhi` and `/sayhi <target>` with the same command name `sayhi`, but have different results based on the arguments used.
 
 You can notice two things:
 
@@ -61,7 +61,7 @@ With optional arguments, there is a possibility of them being not present in the
 
 ## Setting existing arguments as optional arguments
 
-In order to set arguments as optional the CommandAPI has the method `setOptional(boolean)`:
+To set arguments as optional, the CommandAPI has the method `setOptional(boolean)`:
 
 ```java
 Argument setOptional(boolean optional);
@@ -96,7 +96,7 @@ Optional<Object> getOptional(String nodeName)
 
 The examples will be using the `getOptional` methods but there is no downside of using the `getOrDefault` methods.
 
-:::tip Example - `/sayhi` command while using the getOptional method
+::::tip Example - `/sayhi` command while using the getOptional method
 
 Let's register the `/sayhi` command from above a second time - this time using a `getOptional` method. We are using the exact same command syntax:
 
@@ -139,9 +139,13 @@ You will need to use this method if you want to have a required argument after a
 1. You have a `CommandAPICommand` and you add arguments to it.
 2. After your required arguments, you can provide optional arguments.
 
-At this point your command is basically done. Any attempt to add a required argument will result in an `OptionalArgumentException`. However, this is where the `combineWith` method comes in.
-This method allows you to combine arguments. Let's say you have an optional `StringArgument` (here simplified to `A`) and you want a required `PlayerArgument` (here simplified to `B`).
-Argument `B` should only be required if argument `A` is given. To implement that logic, we are going to use the `combineWith` method so that we have this syntax:
+At this point, your command is basically done.
+Any attempt to add a required argument will result in an `OptionalArgumentException`.
+However, this is where the `combineWith` method comes in.
+This method allows you to combine arguments.
+Let's say you have an optional `StringArgument` (here simplified to `A`) and you want a required `PlayerArgument` (here simplified to `B`).
+Argument `B` should only be required if argument `A` is given.
+To implement that logic, we’re going to use the `combineWith` method so that we have this syntax:
 
 ```java
 A.combineWith(B)
@@ -168,7 +172,7 @@ new CommandAPICommand("mycommand")
     .withArguments(C)
 ```
 
-This would result in an `OptionalArgumentException` because you are declaring a required argument after an optional argument without creating that exception for argument `C` like you do for argument `B`.
+This would result in an `OptionalArgumentException` because you’re declaring a required argument after an optional argument without creating that exception for argument `C` like you do for argument `B`.
 
 ::::tip Example - Required arguments after optional arguments
 
@@ -180,7 +184,7 @@ We want to register a command `/rate` with the following syntax:
 /rate <topic> <rating> <target> - Rates a topic with a rating and sends a message to the target
 ```
 
-To implement that structure we make use of the `combineWith` method to make the argument after the optional argument \<topic> required:
+To implement that structure, we make use of the `combineWith` method to make the argument after the optional argument \<topic> required:
 
 :::tabs
 ===Java

docs/en/create-commands/arguments/suggestions/async-suggestions.md

@@ -8,7 +8,7 @@ authors:
 
 # Asynchronous suggestions
 
-In addition to normal suggestions, safely-typed suggestions and suggestions with tooltips, the CommandAPI can support computing the list of suggestions to send to a player asynchronously. This allows you to perform suggestions independent of the main server thread, which is useful for slow operations, such as:
+In addition to normal suggestions, safely typed suggestions and suggestions with tooltips, the CommandAPI can support computing the list of suggestions to send to a player asynchronously. This allows you to perform suggestions independent of the main server thread, which is useful for slow operations, such as:
 
 - Retrieving suggestions from a remote database
 - Retrieving information from the web
@@ -54,7 +54,7 @@ CompletableFuture.supplyAsync(() -> {
 
 ## Asynchronous suggestions examples
 
-::::tip Example - Reading keys from a config file
+::::tip Example – Reading keys from a config file
 
 Say you wanted to write a command to modify your plugin's config file. Since the config file is an external file, you ideally want to access the file in a separate thread to the main server thread to retain performance for players on the server. We have the following command syntax:
 

docs/en/create-commands/arguments/suggestions/safe-suggestions.md

@@ -9,9 +9,9 @@ authors:
 
 # Type-Safe suggestions
 
-So far, we've covered how to replace suggestions using the `replaceSuggestions()` method. The issue with using strings for suggestion listings is that they are prone to errors - it is possible to suggest something which is not actually a valid argument, which makes that suggestion unusable. As a result, some arguments include the `replaceSafeSuggestions()`, which provides type-safety checks for argument suggestions, as well as automatic "Bukkit-to-suggestion" conversion.
+So far, we've covered how to replace suggestions using the `replaceSuggestions()` method. The issue with using strings for suggestion listings is that they’re prone to errors - it is possible to suggest something, which is not actually a valid argument, which makes that suggestion unusable. As a result, some arguments include the `replaceSafeSuggestions()`, which provides type-safety checks for argument suggestions, as well as automatic "Bukkit-to-suggestion" conversion.
 
-The whole point of the safe argument suggestions method is that parameters entered this method are **guaranteed** to work.
+The whole point of the safe argument suggestions method is that parameters entered in this method are **guaranteed** to work.
 
 The use of the safe replace suggestions function is the same as `replaceSuggestions()` from the previous section, except instead of returning a `String[]`, you now return a `T[]`, where `T` is the class corresponding to the argument. This is described in more detail in the table below.
 
@@ -40,7 +40,7 @@ SafeSuggestions<T> tooltipsAsync(Function<SuggestionInfo, CompletableFuture<Tool
 
 Not all arguments support safe suggestions. This is mostly due to implementation constraints or inadequate support by the Bukkit API.
 
-The list of supported arguments are displayed in the following table. The parameter `T` (shown in the method signatures above) are also provided for each argument. This parameter is the same as the cast argument described in [Argument Casting](../command-arguments#argument-casting), except for a few exceptions which are outlined in **bold**.
+The list of supported arguments is displayed in the following table. The parameter `T` (shown in the method the signatures above) are also provided for each argument. This parameter is the same as the cast argument described in [Argument Casting](../command-arguments#argument-casting), except for a few exceptions which are outlined in **bold**.
 
 |                                                                         Argument | Class (T)                                      |
 |---------------------------------------------------------------------------------:|:-----------------------------------------------|
@@ -92,7 +92,7 @@ These create representations of ticks (e.g. `40t`), days (e.g. `2d`) and seconds
 
 ## Safe function arguments
 
-Although all safe arguments are indeed "type-safe", the function argument uses a `NamespacedKey` which cannot be checked fully at compile time. As a result, this is argument should be used with caution - providing a `NamespacedKey` suggestion that does not exist when the server is running will cause that command to fail if that suggestion is used.
+Although all safe arguments are indeed "type-safe", the function argument uses a `NamespacedKey` which cannot be checked fully at compile time. As a result, this is argument should be used with caution - providing a `NamespacedKey` suggestion that doesn’t exist when the server is running will cause that command to fail if that suggestion is used.
 
 ## Safe scoreboard slot arguments