Pre-final revision

Author: Strokkur424

docs/paper/dev/api/command-api/arguments/adventure-arguments.mdx

@@ -10,12 +10,18 @@ import StyleMp4 from "./assets/vanilla-arguments/style.mp4"
 import SignedMessageMp4 from "./assets/vanilla-arguments/signedmessage.mp4"
 
 # Adventure Library Arguments
-These arguments return a class from the `net.kyori` package. They are *technically* not native to Minecraft or Bukkit, but as Paper includes the Adventure library, they are
+These arguments return a class from the `net.kyori` package. They are technically not native to Minecraft or Bukkit, but as Paper includes the Adventure library, they are
 usually widely used in the Paper ecosystem.
 
 ## Component Argument
-The component argument is a very complicated command for the user, which is why it should not be used for usual user input. It follows the same format as the `/tellraw <player> <msg>`
-command for its second argument. It accepts a text component as its json representation, returning it as an Adventure component to work with.
+:::note
+
+This argument is very technical. Following the same format as the `/tellraw <player> <component>` command for its second argument, it expects the json
+representation of a text component, making it inappropriate for general user input.
+
+:::
+
+The result is returned as an Adventure component to work with.
 
 ### Example usage
 ```java
@@ -39,7 +45,6 @@ public static LiteralCommandNode<CommandSourceStack> componentArgument() {
 <FullWidthVideo src={ComponentMp4}/>
 
 
-
 ## Key Argument
 The key argument allows a user to put in any artificial (namespaced) key, ensuring its validity. This returns a `net.kyori.adventure.key.Key` from the adventure library, 
 which can be used at various other places in the Bukkit/Paper API.
@@ -66,11 +71,9 @@ public static LiteralCommandNode<CommandSourceStack> keyArgument() {
 <FullWidthVideo src={KeyMp4}/>
 
 
-
 ## Named Color Argument
-This argument provides the user with the ability to select between the 16 build-in "named" text colors. This argument returns a `net.kyori.adventure.text.format.NamedTextColor` that
-
-you can use for styling components.
+This argument provides the user with the ability to select between the 16 build-in "named" text colors. This argument returns a
+`net.kyori.adventure.text.format.NamedTextColor` which you can use for styling components.
 
 ### Example usage
 ```java
@@ -95,18 +98,16 @@ public static LiteralCommandNode<CommandSourceStack> namedColorArgument() {
 <FullWidthVideo src={NamedColorMp4}/>
 
 
-
 ## Adventure Style Argument
 :::note
 
 Similar to the component argument, this argument is not really appropriate for general user input, as it also follows the json format for displaying components. Most users
-do not know how to use that format and thus its public usage is not advised.
+do not know how to use that format and thus its general usage is not advised.
 
 :::
 
 The style argument returns its value in form of an `net.kyori.adventure.text.format.Style` object. This can be applied to any component using `Component#style(Style)`.
-
-Whilst the json input allows for the `text` field, it does not actually do anything.
+Whilst the json input allows for the `text` field, its content is completely ignored.
 
 ### Example usage
 ```java
@@ -131,9 +132,8 @@ public static LiteralCommandNode<CommandSourceStack> styleArgument() {
 <FullWidthVideo src={StyleMp4}/>
 
 
-
 ## Signed Message Argument
-The signed message argument allows a player (not a console!!) to send an argument in form of a **signed message** to the server. This signed message is a special type - it
+The signed message argument allows a player to send an argument in form of a **signed message** to the server. This signed message is a special type - it
 allows the server to send that message, without the ability to directly modify it, to any player. The visible difference is that unsigned messages have a white bar at the left,
 whilst signed messages don't.
 

docs/paper/dev/api/command-api/arguments/bukkit-arguments.mdx

@@ -15,8 +15,7 @@ The arguments described in this section return objects oftentime used in Bukkit
 non-bukkit object described here is the [UUID Argument](#uuid-argument).
 
 ## Block State Argument
-The block state argument is a very useful argument for getting use input on an exact block type and its data. It is particularly used for commands that modify blocks
-in some way, which requires precise input.
+The block state argument can be used for getting a block type and explicit, assosiated data.
 
 ### Example usage
 ```java
@@ -37,9 +36,8 @@ public static LiteralCommandNode<CommandSourceStack> blockStateArgument() {
 <FullWidthVideo src={BlockStateMp4}/>
 
 
-
 ## ItemStack Argument
-The item stack argument is a way to retrieve an <Javadoc name={'org.bukkit.inventory.ItemStack'}>`ItemStack`</Javadoc> following the same argument format as the vanilla `/give <player> <item> [<amount>]`
+The item stack argument is the way to retrieve an <Javadoc name={'org.bukkit.inventory.ItemStack'}>`ItemStack`</Javadoc> following the same argument format as the vanilla `/give <player> <item> [<amount>]`
 command as its second argument. The user may also define components to further customize the `ItemStack`. If you only require a <Javadoc name={'org.bukkit.Material'}>`Material`</Javadoc>, you should instead
 check out the [registry arguments](./registry-arguments.mdx).
 
@@ -72,10 +70,9 @@ public static LiteralCommandNode<CommandSourceStack> itemStackArgument() {
 <FullWidthVideo src={ItemStackMp4}/>
 
 
-
 ## Bukkit NamespacedKey Argument
-Similar to the **Key** argument, this argument allows the user to provide any artificial (namespaced) key. The difference is that the return value of this argument is instead a
-<Javadoc name={'org.bukkit.NamespacedKey'}>`NamespacedKey`</Javadoc>, which makes it particularly useful when dealing with Bukkit API.
+This argument allows the user to provide any artificial (namespaced) key. The return value of this argument is a
+<Javadoc name={'org.bukkit.NamespacedKey'}>`NamespacedKey`</Javadoc>, which makes it useful when dealing with Bukkit API.
 
 ### Example usage
 ```java
@@ -98,7 +95,6 @@ public static LiteralCommandNode<CommandSourceStack> namespacedKeyArgument() {
 <FullWidthVideo src={NamespacedKeyMp4}/>
 
 
-
 ## Time Argument
 The time argument allows the user to define a time frame, similar to the vanilla `/time <set|time> <time>` time argument. The user has 4 possible ways of inputting time:
 * Just as a number: This resolves to as usual ticks (`/timearg 1` --> 1 tick)
@@ -137,7 +133,6 @@ public static LiteralCommandNode<CommandSourceStack> timeArgument() {
 <FullWidthVideo src={TimeMp4}/>
 
 
-
 ## UUID Argument
 The uuid argument allows the user to input a valid uuid. You can retrieve that value as a `UUID` object, which is used in various places, like `Bukkit.getOfflinePlayer(UUID)`.
 This argument is not very user-friendly, which is why it is suggested to only use this as a moderation or debug argument. For user input regarding offline player
@@ -167,10 +162,8 @@ public static LiteralCommandNode<CommandSourceStack> uuidArgument() {
 <FullWidthVideo src={UuidMp4}/>
 
 
-
 ## Objective Criteria Argument
-This argument has wide usage when dealing with scoreboard objectives and scores. You can retrieve the argument value as a `Criteria` enum value, which can be
-used with Scoreboard objects.
+You can retrieve the argument value as a `Criteria` enum value, which can be used with Scoreboard objects.
 
 ### Example usage
 ```java

docs/paper/dev/api/command-api/arguments/entity-player-arguments.mdx

@@ -46,7 +46,6 @@ If the executing player is opped:
 <FullWidthVideo src={EntityOppedMp4}/>
 
 
-
 ## Entities Argument
 In contrast to the single entity argument, this multi entity argument accepts any amount of entities, with the minimum amount of entities being 1. They can, once again, be resolved using
 <Javadoc name="io.papermc.paper.command.brigadier.argument.resolvers.ArgumentResolver#resolve(io.papermc.paper.command.brigadier.CommandSourceStack)">`ArgumentResolver#resolve(CommandSourceStack)`</Javadoc>,
@@ -75,14 +74,14 @@ public static LiteralCommandNode<CommandSourceStack> entities() {
 <FullWidthVideo src={EntitiesMp4}/>
 
 
-
 ## Player Argument
-The player argument allows you to be given some player input. Running `ctx.getArgument` return a `PlayerSelectorArgumentResolver` for player arguments. 
+The player argument allows to retrieve a `PlayerSelectorArgumentResolver` for player arguments.
 For this "single player" argument, you can safely get the target player by running `PlayerSelectorArgumentResolver.resolve(ctx.getSource()).getFirst()`,
-which returns a Bukkit <Javadoc name='org.bukkit.entity.Player'>`Player`</Javadoc> object.
+which returns a <Javadoc name='org.bukkit.entity.Player'>Player</Javadoc> object.
 
 ### Example usage
 This command yeets the targeted player into the air!
+
 ```java
 public static LiteralCommandNode<CommandSourceStack> playerArgument() {
     return Commands.literal("player")
@@ -107,14 +106,14 @@ public static LiteralCommandNode<CommandSourceStack> playerArgument() {
 <FullWidthVideo src={PlayerMp4}/>
 
 
-
 ## Players Argument
-The "multiple players" argument works similarly to the Player argument, also returning a `PlayerSelectorArgumentResolver`. Instead of just resolving to exactly one `Player`, this
+The "multiple players" argument works similarly to the "single player" argument, also returning a `PlayerSelectorArgumentResolver`. Instead of just resolving to exactly one `Player`, this
 one can resolve to more than just one player - which you should account for in case of using this argument. `PlayerSelectorArgumentResolver.resolve#(ctx.getSource())` returns a
 `List<Player>`, which you can just iterate through.
 
 ### Example usage
-Extending the "single player" yeet command to support multiple targets
+Extending the "single player" yeet command to support multiple targets can look like this:
+
 ```java
 public static LiteralCommandNode<CommandSourceStack> playersArgument() {
     return Commands.literal("players")
@@ -142,15 +141,16 @@ public static LiteralCommandNode<CommandSourceStack> playersArgument() {
 <FullWidthVideo src={PlayersMp4}/>
 
 
-
 ## Player Profiles Argument
 The player profiles argument is a very powerful argument which can retrieve both offline and online players. It returns the result of the argument as a `PlayerProfileListResolver`,
 which resolves to a `Collection<PlayerProfile>`. This collection can be iterated to get the resulting profile(s). Usually, it only returns a single `PlayerProfile` if retrieving
 a player by name, but it can return multiple if using the entity selectors (like `@a` on online players). Thus it always makes sense to run whatever operation you want to run on
 all entries in the collection instead of just the first one.
 
-Sometimes, the API call to players, which are currently offline and have no yet logged onto the server, may fail. This is also visible in the in-game preview down below. This
-weird behavior also explains why the `/whitelist add` command sometimes fails.
+This argument will run API calls to Mojang servers in order to retrieve player information for players which have never joined the server before. Due to this operation sometimes
+taking a bit longer, it is suggested to resolve this argument in an asynchronous context in order to not cause any server lag.
+
+Sometimes, theese API calls may fail. This is also visible in the in-game preview down below. This behavior is also the reason for `/whitelist add` sometimes.
 
 ### Example usage - Player lookup command
 ```java

docs/paper/dev/api/command-api/arguments/enum-value-arguments.mdx

@@ -11,7 +11,6 @@ import TemplateMirrorMp4 from "./assets/vanilla-arguments/templatemirror.mp4"
 import TemplateRotationMp4 from "./assets/vanilla-arguments/templaterotation.mp4"
 
 # Enum Value Arguments
-These arguments return a value from an enum class.
 
 ## Entity Anchor Argument
 The entity anchor argument has two valid inputs: `feet` and `eyes`. The resulting <Javadoc name='io.papermc.paper.entity.LookAnchor'>`LookAnchor`</Javadoc> is mainly used for methods like
@@ -122,7 +121,7 @@ public static LiteralCommandNode<CommandSourceStack> scoreboardDisplaySlotArgume
 
 
 ## Template Mirror Argument
-This argument is a very simple enum argument. The user has 3 valid input possibilities: `front_back`, `left_right`, and `none`. You can retrieve the result of 
+Here, the user has 3 valid input possibilities: `front_back`, `left_right`, and `none`. You can retrieve the result of 
 the argument as a <Javadoc name='org.bukkit.block.structure.Mirror'>`Mirror`</Javadoc> enum value.
 
 ### Example usage

docs/paper/dev/api/command-api/arguments/location-arguments.mdx

@@ -8,8 +8,6 @@ import FinePositionMp4 from "./assets/vanilla-arguments/fineposition.mp4"
 import WorldMp4 from "./assets/vanilla-arguments/world.mp4"
 
 # Location Arguments
-With the arguments described in this page, you can retrieve positional input from a user.
-
 
 ## Block Position Argument
 The block position argument is used for retrieving the position of a block. It works the same way as the first argument of the `/setblock <position> <block>` vanilla command.
@@ -38,7 +36,7 @@ public static LiteralCommandNode<CommandSourceStack> blockPositionArgument() {
 
 ## Fine Position Argument
 The fine position argument works similarly to the block position argument, with the only difference being that it can accept decimal (precise) location input. The optional
-overload (`ArgumentTypes.finePosition(boolean centerIntegers)`), which defaults to false if not set, will center whole input, meaning 5 becomes 5.5 (5.0 would stay as 5.5 though),
+overload (`ArgumentTypes.finePosition(boolean centerIntegers)`), which defaults to false if not set, will center whole input, meaning 5 becomes 5.5 (5.0 would stay as 5.0 though),
 as that is the "middle" of a block. This only applies to X/Z. The y coordinate is untouched by this operation.
 
 This argument returns a <Javadoc name='io.papermc.paper.command.brigadier.argument.resolvers.FinePositionResolver'>`FinePositionResolver`</Javadoc>. You can resolve that by running `FinePositionResolver#resolve(CommandSourceStack)` to get the resulting

docs/paper/dev/api/command-api/arguments/minecraft-arguments.mdx

@@ -6,7 +6,7 @@ toc_max_heading_level: 4
 ---
 
 # Minecraft Arguments
-The [Arguments and Literals](../basics/arguments-and-literals) page covers the most used, native Brigadier arguments. But Minecraft (and Paper) defines a few more. These can be accessed
+The [Arguments and Literals](../basics/arguments-and-literals) page covers the most used, native Brigadier arguments. But Minecraft (and Paper) define a few more. These can be accessed
 in a static context using the <Javadoc name='io.papermc.paper.command.brigadier.argument.ArgumentTypes'>`ArgumentTypes`</Javadoc> class. We will go over all of those in this section.
 
 ## Quick overview

docs/paper/dev/api/command-api/arguments/predicate-arguments.mdx

@@ -12,8 +12,7 @@ A predicate allows for checking for valid values. These arguments are dedicated
 
 
 ## Double Range argument
-With the double range argument you can define a double, or a range/amount of doubles, which can act as a predicate for numbers. This could be used for an 
-argument which kill all enemies in a specific range or for clearing items in a range of slots. As this argument is rather technical, it is not used very often.
+This argument can be used as a predicate for numbers, which require precise input.
 
 ### Example usage
 ```java
@@ -40,7 +39,6 @@ public static LiteralCommandNode<CommandSourceStack> doubleRange() {
 <FullWidthVideo src={DoubleRangeMp4}/>
 
 
-
 ## Integer Range Argument
 This argument works very similarly to the double range argument, with the only difference being that this argument only accepts integers.
 
@@ -77,7 +75,6 @@ private static int runIntegerRangeCommand(final CommandContext<CommandSourceStac
 <FullWidthVideo src={IntegerRangeMp4}/>
 
 
-
 ## Item Predicate Argument
 This argument allows for checking whether an item fits some predicate. It is useful for filtering out certain items based on some criteria.
 

docs/paper/dev/api/command-api/arguments/registry-arguments.mdx

@@ -32,15 +32,11 @@ import EnchantsRegistry from "./assets/registry-arguments/enchants-registry.mp4"
 
 # Registry Arguments
 Registries in Minecraft hold all sort of information - possible item materials, block materials, enchantments, potion effects, ... and more!
-These arguments are particularly useful for retrieving type values.
 
-There are **two** types of registry arguments: `resource` and `resourceKey`. 
+There are two types of registry arguments: `resource` and `resourceKey`. 
 The main difference between those arguments is the return value: The `resource` argument returns the parsed value, whilst the `resourceKey` only returns a `TypedKey`, which
 you can use to retrieve the value yourself.
 
-For more information on the `resourceKey` argument, check out [its dedicated segment](#resource-key-argument).
-
-
 ## Resource Argument
 Just like any other argument, you can get a `ArgumentType<T>` reference to it using `ArgumentTypes.resource(RegistryKey<T>)`. A selection of possible registry keys can be
 found below. They are accessed in a static context using the <Javadoc name='io.papermc.paper.registry.RegistryKey'>`RegistryKey`</Javadoc> interface.
@@ -96,14 +92,13 @@ There are certain edge-cases, where this argument, due to missing registries on
 Basically, the only argument where this is the case right now is with the `STRUCTURE` registry key.
 
 ```java
-// Registering this command will cause client to not be able to connect to the server.
+// Registering this command will cause clients to not be able to connect to the server.
 final LiteralCommandNode<CommandSourceStack> invalidRegistryArgument = Commands.literal("registry-structure")
     .then(Commands.argument("value", ArgumentTypes.resource(RegistryKey.STRUCTURE)))
     .build();
 ```
 
 Due to this fact, it is advised to only use the `STRUCTURE` registry key argument with a `resourceKey(...)` argument type and parse the values yourself.
-[More information on resource key arguments can be found by clicking here.](#resource-key-argument).
 
 :::