Refactor code examples

Strokkur424 · Strokkur424 · commit b7d1f8f83acb · 2025-01-15T16:33:49.000+01:00
diff --git a/docs/paper/dev/api/command-api/arguments/entity-player.mdx b/docs/paper/dev/api/command-api/arguments/entity-player.mdx
@@ -162,7 +162,7 @@ public static LiteralCommandNode<CommandSourceStack> playerProfilesArgument() {
                 final Collection<PlayerProfile> foundProfiles = profilesResolver.resolve(ctx.getSource());
 
                 for (final PlayerProfile profile : foundProfiles) {
-                    ctx.getSource().getSender().sendMessage("Found " + profile.getName());
+                    ctx.getSource().getSender().sendPlainMessage("Found " + profile.getName());
                 }
 
                 return Command.SINGLE_SUCCESS;
diff --git a/docs/paper/dev/api/command-api/arguments/enums.mdx b/docs/paper/dev/api/command-api/arguments/enums.mdx
@@ -57,7 +57,7 @@ public static LiteralCommandNode<CommandSourceStack> gameModeArgument() {
                     );
                 }
                 else {
-                    ctx.getSource().getSender().sendRichMessage("This command requires a player!");
+                    ctx.getSource().getSender().sendPlainMessage("This command requires a player!");
                 }
                 
                 return Command.SINGLE_SUCCESS;
@@ -108,7 +108,7 @@ public static LiteralCommandNode<CommandSourceStack> scoreboardDisplaySlotArgume
             .executes(ctx -> {
                 final DisplaySlot slot = ctx.getArgument("slot", DisplaySlot.class);
                 
-                ctx.getSource().getSender().sendMessage("You selected: " + slot.getId());
+                ctx.getSource().getSender().sendPlainMessage("You selected: " + slot.getId());
                 
                 return Command.SINGLE_SUCCESS;
             })
@@ -132,7 +132,7 @@ public static LiteralCommandNode<CommandSourceStack> templateMirrorArgument() {
             .executes(ctx -> {
                 final Mirror mirror = ctx.getArgument("mirror", Mirror.class);
 
-                ctx.getSource().getSender().sendMessage("You selected: " + mirror.name());
+                ctx.getSource().getSender().sendPlainMessage("You selected: " + mirror.name());
 
                 return Command.SINGLE_SUCCESS;
             })
@@ -156,7 +156,7 @@ public static LiteralCommandNode<CommandSourceStack> templateRotationArgument()
             .executes(ctx -> {
                 final StructureRotation rotation = ctx.getArgument("rotation", StructureRotation.class);
 
-                ctx.getSource().getSender().sendMessage("You selected: " + rotation.name());
+                ctx.getSource().getSender().sendPlainMessage("You selected: " + rotation.name());
 
                 return Command.SINGLE_SUCCESS;
             })
diff --git a/docs/paper/dev/api/command-api/arguments/location.mdx b/docs/paper/dev/api/command-api/arguments/location.mdx
@@ -23,7 +23,7 @@ public static LiteralCommandNode<CommandSourceStack> blockPositionArgument() {
                 final BlockPositionResolver blockPositionResolver = ctx.getArgument("arg", BlockPositionResolver.class);
                 final BlockPosition blockPosition = blockPositionResolver.resolve(ctx.getSource());
 
-                ctx.getSource().getSender().sendMessage("Put in " + blockPosition.x() + " " + blockPosition.y() + " " + blockPosition.z());
+                ctx.getSource().getSender().sendPlainMessage("Put in " + blockPosition.x() + " " + blockPosition.y() + " " + blockPosition.z());
                 return Command.SINGLE_SUCCESS;
             }))
         .build();
diff --git a/docs/paper/dev/api/command-api/arguments/paper.mdx b/docs/paper/dev/api/command-api/arguments/paper.mdx
@@ -10,7 +10,8 @@ import TimeMp4 from "./assets/vanilla-arguments/time.mp4";
 import UuidMp4 from "./assets/vanilla-arguments/uuid.mp4";
 import ObjectiveCriteriaMp4 from "./assets/vanilla-arguments/objectivecriteria.mp4";
 
-# Arguments for Types Frequently Used in Paper API
+# Paper Arguments
+The arguments in this section return objects frequently used in Paper API.
 
 ## Block state argument
 The block state argument can be used for getting a block type and explicit, associated data.
@@ -23,7 +24,7 @@ public static LiteralCommandNode<CommandSourceStack> blockStateArgument() {
             .executes(ctx -> {
                 final BlockState blockState = ctx.getArgument("arg", BlockState.class);
                 
-                ctx.getSource().getSender().sendMessage("You specified a " + blockState.getType() + "!");
+                ctx.getSource().getSender().sendPlainMessage("You specified a " + blockState.getType() + "!");
                 return Command.SINGLE_SUCCESS;
             }))
         .build();
@@ -118,7 +119,7 @@ public static LiteralCommandNode<CommandSourceStack> timeArgument() {
                     player.sendRichMessage("Moved time forward by " + timeInTicks + " ticks!");
                 }
                 else {
-                    ctx.getSource().getSender().sendMessage("This argument requires a player!");
+                    ctx.getSource().getSender().sendPlainMessage("This argument requires a player!");
                 }
 
                 return Command.SINGLE_SUCCESS;
diff --git a/docs/paper/dev/api/command-api/basics/executors.mdx b/docs/paper/dev/api/command-api/basics/executors.mdx
@@ -55,13 +55,15 @@ Commands.literal("flyspeed")
     .then(Commands.argument("speed", FloatArgumentType.floatArg(0, 1.0f))
         .executes(ctx -> {
             float speed = ctx.getArgument("speed", float.class); // Retrieve the speed argument
+            // highlight-next-line
             CommandSender sender = ctx.getSource().getSender(); // Retrieve the command sender
+            // highlight-next-line
             Entity executor = ctx.getSource().getExecutor(); // Retrieve the command executor, which may or may not be the same as the sender
     
             // Check whether the executor is a player, as you can only set a player's flight speed
             if (!(executor instanceof Player player)) {
                 // If a non-player tried to set their own flight speed
-                sender.sendMessage("Only players can fly!");
+                sender.sendPlainMessage("Only players can fly!");
                 return Command.SINGLE_SUCCESS;
             }
     
@@ -70,12 +72,12 @@ Commands.literal("flyspeed")
     
             if (sender == executor) {
                 // If the player executed the command themselves
-                player.sendMessage(Component.text("Successfully set your flight speed to " + speed));
+                player.sendPlainMessage("Successfully set your flight speed to " + speed);
             }
             else {
                 // If the speed was set by a different sender (Like using /execute)
                 sender.sendRichMessage("Successfully set <playername>'s flight speed to " + speed, Placeholder.component("playername", player.name()));
-                player.sendMessage(Component.text("Your flight speed has been set to " + speed));
+                player.sendPlainMessage("Your flight speed has been set to " + speed);
             }
     
             return Command.SINGLE_SUCCESS;
@@ -133,23 +135,28 @@ public class FlightSpeedCommand {
     }
 
     private static int runFlySpeedLogic(CommandContext<CommandSourceStack> ctx) {
-        float speed = ctx.getArgument("speed", float.class);
-        CommandSender sender = ctx.getSource().getSender();
-        Entity executor = ctx.getSource().getExecutor();
+        float speed = ctx.getArgument("speed", float.class); // Retrieve the speed argument
+        CommandSender sender = ctx.getSource().getSender(); // Retrieve the command sender
+        Entity executor = ctx.getSource().getExecutor(); // Retrieve the command executor, which may or may not be the same as the sender
+
+        // Check whether the executor is a player, as you can only set a player's flight speed
+        if (!(executor instanceof Player player)) {
+            // If a non-player tried to set their own flight speed
+            sender.sendPlainMessage("Only players can fly!");
+            return Command.SINGLE_SUCCESS;
+        }
 
-        if (executor instanceof Player player) {
-            player.setFlySpeed(speed);
+        // Set the player's speed
+        player.setFlySpeed(speed);
 
-            if (sender == executor) {
-                player.sendMessage("Successfully set your flight speed to " + speed);
-            }
-            else {
-                sender.sendMessage("Successfully set " + player.getName() + "'s flight speed to " + speed);
-                player.sendMessage("Your flight speed has been set to " + speed);
-            }
+        if (sender == executor) {
+            // If the player executed the command themselves
+            player.sendPlainMessage("Successfully set your flight speed to " + speed);
         }
         else {
-            sender.sendMessage("Consoles can't fly!");
+            // If the speed was set by a different sender (Like using /execute)
+            sender.sendRichMessage("Successfully set <playername>'s flight speed to " + speed, Placeholder.component("playername", player.name()));
+            player.sendPlainMessage("Your flight speed has been set to " + speed);
         }
 
         return Command.SINGLE_SUCCESS;
diff --git a/docs/paper/dev/api/command-api/misc/basic-command.mdx b/docs/paper/dev/api/command-api/misc/basic-command.mdx
@@ -26,7 +26,9 @@ package your.package.name;
 
 import io.papermc.paper.command.brigadier.BasicCommand;
 import io.papermc.paper.command.brigadier.CommandSourceStack;
+import org.jspecify.annotations.NullMarked;
 
+@NullMarked
 public class YourCommand implements BasicCommand {
 
     @Override
@@ -62,13 +64,15 @@ With the permission method you can, similar to the `canUse` method, set the perm
 ## Example: Broadcast command
 As an example, we can create a simple broadcast command. We start by declaring creating a class which implements `BasicCommand` and overrides `execute` and `permission`:
 
-```java
+```java title="BroadcastCommand.java"
 package your.package.name;
 
 import io.papermc.paper.command.brigadier.BasicCommand;
 import io.papermc.paper.command.brigadier.CommandSourceStack;
-import org.jetbrains.annotations.Nullable;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
+@NullMarked
 public class BroadcastCommand implements BasicCommand {
 
     @Override
@@ -134,8 +138,10 @@ import net.kyori.adventure.text.Component;
 import net.kyori.adventure.text.minimessage.MiniMessage;
 import net.kyori.adventure.text.minimessage.tag.resolver.Placeholder;
 import org.bukkit.Bukkit;
-import org.jetbrains.annotations.Nullable;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
+@NullMarked
 public class BroadcastCommand implements BasicCommand {
 
     @Override
@@ -237,10 +243,12 @@ import net.kyori.adventure.text.minimessage.MiniMessage;
 import net.kyori.adventure.text.minimessage.tag.resolver.Placeholder;
 import org.bukkit.Bukkit;
 import org.bukkit.entity.Player;
-import org.jetbrains.annotations.Nullable;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 import java.util.Collection;
 
+@NullMarked
 public class BroadcastCommand implements BasicCommand {
 
     @Override
diff --git a/docs/paper/dev/api/command-api/misc/comparison-bukkit-brigadier.mdx b/docs/paper/dev/api/command-api/misc/comparison-bukkit-brigadier.mdx
@@ -14,31 +14,42 @@ import PaperPartyCommandImage from "./assets/paperparty-command.png";
 In order to register Bukkit commands, you would define a class that extends `BukkitCommand`, and implements the `execute(...)` and `tabComplete(...)`
 methods. This might look like this:
 ```java title="BukkitPartyCommand.java"
+package your.package.name;
+
+import org.bukkit.Bukkit;
+import org.bukkit.command.CommandSender;
+import org.bukkit.command.defaults.BukkitCommand;
+import org.bukkit.entity.Player;
+import org.jspecify.annotations.NullMarked;
+
+import java.util.List;
+
+@NullMarked
 public class BukkitPartyCommand extends BukkitCommand {
-    public BukkitPartyCommand(@NotNull String name, @NotNull String description, @NotNull String usageMessage, @NotNull List<String> aliases) {
+    public BukkitPartyCommand(String name, String description, String usageMessage, List<String> aliases) {
         super(name, description, usageMessage, aliases);
     }
 
     @Override
-    public boolean execute(@NotNull CommandSender sender, @NotNull String commandLabel, @NotNull String[] args) {
+    public boolean execute(CommandSender sender, String commandLabel, String[] args) {
         if (args.length == 0) {
-            sender.sendMessage("Please provide a player!");
+            sender.sendPlainMessage("Please provide a player!");
             return true;
         }
 
         final Player targetPlayer = Bukkit.getPlayer(args[0]);
         if (targetPlayer == null) {
-            sender.sendMessage("Please provide a valid player!");
+            sender.sendPlainMessage("Please provide a valid player!");
             return true;
         }
 
-        targetPlayer.sendMessage(sender.getName() + " started partying with you!");
-        sender.sendMessage("You are now partying with " + targetPlayer.getName() + "!");
+        targetPlayer.sendPlainMessage(sender.getName() + " started partying with you!");
+        sender.sendPlainMessage("You are now partying with " + targetPlayer.getName() + "!");
         return false;
     }
 
     @Override
-    public @NotNull List<String> tabComplete(@NotNull CommandSender sender, @NotNull String alias, @NotNull String[] args) throws IllegalArgumentException {
+    public List<String> tabComplete(CommandSender sender, String alias, String[] args) throws IllegalArgumentException {
         if (args.length == 1) {
             return Bukkit.getOnlinePlayers().stream().map(Player::getName).toList();
         }
@@ -76,8 +87,8 @@ public static LiteralCommandNode<CommandSourceStack> createCommand(final String
                 final Player targetPlayer = playerSelector.resolve(ctx.getSource()).getFirst();
                 final CommandSender sender = ctx.getSource().getSender();
 
-                targetPlayer.sendMessage(sender.getName() + " started partying with you!");
-                sender.sendMessage("You are now partying with " + targetPlayer.getName() + "!");
+                targetPlayer.sendPlainMessage(sender.getName() + " started partying with you!");
+                sender.sendPlainMessage("You are now partying with " + targetPlayer.getName() + "!");
 
                 return Command.SINGLE_SUCCESS;
             }))

Original file line number	Diff line number	Diff line change
`@@ -162,7 +162,7 @@ public static LiteralCommandNode<CommandSourceStack> playerProfilesArgument() {`
`162`	`162`	`final Collection<PlayerProfile> foundProfiles = profilesResolver.resolve(ctx.getSource());`
`163`	`163`
`164`	`164`	`for (final PlayerProfile profile : foundProfiles) {`
`165`		`- ctx.getSource().getSender().sendMessage("Found " + profile.getName());`
	`165`	`+ ctx.getSource().getSender().sendPlainMessage("Found " + profile.getName());`
`166`	`166`	`}`
`167`	`167`
`168`	`168`	`return Command.SINGLE_SUCCESS;`