Implement the majority of CommandAPI#528. Implement the main logic and documentation examples (Java, Kotlin). Fix typo in Kotlin DSL example

Only thing left to do with this is manual testing, implementing this for the Kotlin DSL, and adding a global and documentation changelog entry

Author: JorelAli

commandapi-core/src/main/java/dev/jorel/commandapi/CommandAPIHandler.java

@@ -603,6 +603,7 @@ void register(CommandMetaData<CommandSender> meta, final Argument[] args,
 		Optional<String> shortDescription = meta.shortDescription;
 		Optional<String> fullDescription = meta.fullDescription;
 		Optional<String[]> usageDescription = meta.usageDescription;
+		Optional<Object> helpTopic = meta.helpTopic;
 
 		// Handle command conflicts
 		boolean hasRegisteredCommand = false;
@@ -619,7 +620,7 @@ void register(CommandMetaData<CommandSender> meta, final Argument[] args,
 			argumentsString.add(arg.getNodeName() + ":" + arg.getClass().getSimpleName());
 		}
 		RegisteredCommand registeredCommandInformation = new RegisteredCommand(commandName, argumentsString, List.of(args), shortDescription,
-			fullDescription, usageDescription, aliases, permission, namespace);
+			fullDescription, usageDescription, helpTopic, aliases, permission, namespace);
 		registeredCommands.add(registeredCommandInformation);
 
 		// Handle previewable arguments

commandapi-core/src/main/java/dev/jorel/commandapi/CommandMetaData.java

@@ -47,6 +47,11 @@ final class CommandMetaData<CommandSender> {
 	 */
 	Optional<String[]> usageDescription = Optional.empty();
 
+	/**
+	 * An optional HelpTopic object for the command (for Bukkit)
+	 */
+	Optional<Object> helpTopic = Optional.empty();
+	
 	/**
 	 * Create command metadata
 	 * @param commandName The command's name
@@ -69,6 +74,7 @@ public CommandMetaData(CommandMetaData<CommandSender> original) {
 		this.shortDescription = original.shortDescription.isPresent() ? Optional.of(original.shortDescription.get()) : Optional.empty();
 		this.fullDescription = original.fullDescription.isPresent() ? Optional.of(original.fullDescription.get()) : Optional.empty();
 		this.usageDescription = original.usageDescription.isPresent() ? Optional.of(original.usageDescription.get()) : Optional.empty();
+		this.helpTopic = original.helpTopic.isPresent() ? Optional.of(original.helpTopic.get()) : Optional.empty();
 	}
 
 }

commandapi-core/src/main/java/dev/jorel/commandapi/RegisteredCommand.java

@@ -50,6 +50,11 @@ public record RegisteredCommand(
 	 *          usage
 	 */
 	Optional<String[]> usageDescription,
+	
+	/**
+	 * @return An {@link Optional} containing this command's help topic (for Bukkit)
+	 */
+	Optional<Object> helpTopic,
 
 	/**
 	 * @return a {@link String}{@code []} of aliases for this command
@@ -74,7 +79,7 @@ public int hashCode() {
 		int result = 1;
 		result = prime * result + Arrays.hashCode(aliases);
 		result = prime * result + Arrays.hashCode(usageDescription.orElse(null));
-		result = prime * result + Objects.hash(argsAsStr, commandName, fullDescription, permission, shortDescription, namespace);
+		result = prime * result + Objects.hash(argsAsStr, commandName, fullDescription, permission, shortDescription, helpTopic, namespace);
 		return result;
 	}
 
@@ -89,14 +94,15 @@ public boolean equals(Object obj) {
 		RegisteredCommand other = (RegisteredCommand) obj;
 		return Arrays.equals(aliases, other.aliases) && Objects.equals(argsAsStr, other.argsAsStr) && Objects.equals(commandName, other.commandName)
 			&& Objects.equals(namespace, other.namespace) && Arrays.equals(usageDescription.orElse(null), other.usageDescription.orElse(null))
-			&& Objects.equals(fullDescription, other.fullDescription) && Objects.equals(permission, other.permission) && Objects.equals(shortDescription, other.shortDescription);
+			&& Objects.equals(fullDescription, other.fullDescription) && Objects.equals(permission, other.permission) && Objects.equals(shortDescription, other.shortDescription)
+			&& Objects.equals(helpTopic, other.helpTopic);
 	}
 
 	@Override
 	public String toString() {
 		return "RegisteredCommand [commandName=" + commandName + ", argsAsStr=" + argsAsStr + ", shortDescription=" + shortDescription + ", fullDescription=" + fullDescription
 			+ ", usageDescription=" + (usageDescription.isPresent() ? "Optional[" + Arrays.toString(usageDescription.get()) + "]" : "Optional.empty")
-			+ ", aliases=" + Arrays.toString(aliases) + ", permission=" + permission + ", namespace=" + namespace + "]";
+			+ ", aliases=" + Arrays.toString(aliases) + ", permission=" + permission + ", namespace=" + namespace + ", helpTopic=" + helpTopic + "]";
 	}
 
 }

commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java

@@ -54,6 +54,7 @@
 import org.bukkit.command.ProxiedCommandSender;
 import org.bukkit.enchantments.Enchantment;
 import org.bukkit.entity.*;
+import org.bukkit.help.HelpTopic;
 import org.bukkit.inventory.ComplexRecipe;
 import org.bukkit.inventory.ItemStack;
 import org.bukkit.inventory.Recipe;
@@ -1682,6 +1683,52 @@ void help() {
 /* ANCHOR_END: help2 */
 }
 
+/* ANCHOR: help3 */
+public HelpTopic makeHelp(String command) {
+    return new HelpTopic() {
+
+        @Override
+        public String getShortText() {
+            return "Says hi";
+        }
+
+        @Override
+        public String getFullText(CommandSender forWho) {
+            String helpText = "";
+            if (forWho instanceof Player player) {
+                // Make use of the player's locale to make language-specific help!
+                Locale playerLocale = player.locale();
+                if (playerLocale.getLanguage().equals("en")) {
+                    helpText = "Broadcasts hi to everyone on the server";
+                } else if (playerLocale.getLanguage().equals("de")) {
+                    helpText = "Sendet Hallo an alle auf dem Server";
+                }
+            } else {
+                helpText = "Broadcasts hi to everyone on the server";
+            }
+            return helpText;
+        }
+
+        // Allow anyone to see this help topic
+        @Override
+        public boolean canSee(CommandSender player) {
+            return true;
+        }
+    };
+}
+/* ANCHOR_END: help3 */
+
+void help2() {
+/* ANCHOR: help4 */
+new CommandAPICommand("mycmd")
+    .withHelp(makeHelp("mycmd"))
+    .executes((sender, args) -> {
+        Bukkit.broadcastMessage("Hi!");
+    })
+    .register();
+/* ANCHOR_END: help4 */
+}
+
 void listed() {
 /* ANCHOR: listed1 */
 new CommandAPICommand("mycommand")

commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt

@@ -36,6 +36,7 @@ import org.bukkit.command.CommandSender
 import org.bukkit.command.ProxiedCommandSender
 import org.bukkit.enchantments.Enchantment
 import org.bukkit.entity.*
+import org.bukkit.help.HelpTopic
 import org.bukkit.inventory.ComplexRecipe
 import org.bukkit.inventory.ItemStack
 import org.bukkit.inventory.Recipe
@@ -1603,6 +1604,42 @@ CommandAPICommand("mycmd")
 /* ANCHOR_END: help2 */
 }
 
+/* ANCHOR: help3 */
+fun makeHelp(command: String): HelpTopic = object: HelpTopic() {
+    override fun getShortText(): String = "Says hi"
+
+    override fun getFullText(forWho: CommandSender): String {
+        var helpText = ""
+        if (forWho is Player) {
+            // Make use of the player's locale to make language-specific help!
+            val playerLocale = forWho.locale()
+            if (playerLocale.getLanguage() == "en") {
+                helpText = "Broadcasts hi to everyone on the server"
+            } else if (playerLocale.getLanguage() == "de") {
+                helpText = "Sendet Hallo an alle auf dem Server"
+            }
+        } else {
+            helpText = "Broadcasts hi to everyone on the server"
+        }
+        return helpText
+    }
+
+    // Allow anyone to see this help topic
+    override fun canSee(player: CommandSender): Boolean = true
+}
+/* ANCHOR_END: help3 */
+
+fun help2() {
+/* ANCHOR: help4 */
+return CommandAPICommand("mycmd")
+    .withHelp(makeHelp("mycmd"))
+    .executes(CommandExecutor { _, _ ->
+        Bukkit.broadcastMessage("Hi!")
+    })
+    .register()
+/* ANCHOR_END: help4 */
+}
+
 fun listed() {
 /* ANCHOR: listed1 */
 CommandAPICommand("mycommand")

commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/ExamplesKotlinDSL.kt

@@ -910,7 +910,7 @@ fun help() {
 /* ANCHOR: help1 */
 commandAPICommand("mycmd") {
     withShortDescription("Says hi")
-    withFullDescription("Broadcasts ho to everyone on the server")
+    withFullDescription("Broadcasts hi to everyone on the server")
     anyExecutor { _, _ ->
         Bukkit.broadcastMessage("Hi!")
     }

commandapi-platforms/commandapi-bukkit/commandapi-bukkit-core/src/main/java/dev/jorel/commandapi/CommandAPIBukkit.java

@@ -7,18 +7,33 @@
 
 import java.io.File;
 import java.io.IOException;
-import java.util.*;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
 import java.util.function.Function;
 import java.util.function.Predicate;
 import java.util.logging.Level;
 import java.util.logging.Logger;
 
-import dev.jorel.commandapi.arguments.AbstractArgument;
-import dev.jorel.commandapi.commandsenders.*;
 import org.bukkit.Bukkit;
 import org.bukkit.ChatColor;
 import org.bukkit.Keyed;
-import org.bukkit.command.*;
+import org.bukkit.command.BlockCommandSender;
+import org.bukkit.command.Command;
+import org.bukkit.command.CommandMap;
+import org.bukkit.command.CommandSender;
+import org.bukkit.command.ConsoleCommandSender;
+import org.bukkit.command.PluginCommand;
+import org.bukkit.command.ProxiedCommandSender;
+import org.bukkit.command.RemoteConsoleCommandSender;
+import org.bukkit.command.SimpleCommandMap;
 import org.bukkit.entity.Player;
 import org.bukkit.event.EventHandler;
 import org.bukkit.event.EventPriority;
@@ -38,10 +53,22 @@
 import com.mojang.brigadier.tree.LiteralCommandNode;
 import com.mojang.brigadier.tree.RootCommandNode;
 
+import dev.jorel.commandapi.arguments.AbstractArgument;
 import dev.jorel.commandapi.arguments.Argument;
 import dev.jorel.commandapi.arguments.LiteralArgument;
 import dev.jorel.commandapi.arguments.MultiLiteralArgument;
 import dev.jorel.commandapi.arguments.SuggestionProviders;
+import dev.jorel.commandapi.commandsenders.AbstractCommandSender;
+import dev.jorel.commandapi.commandsenders.AbstractPlayer;
+import dev.jorel.commandapi.commandsenders.BukkitBlockCommandSender;
+import dev.jorel.commandapi.commandsenders.BukkitCommandSender;
+import dev.jorel.commandapi.commandsenders.BukkitConsoleCommandSender;
+import dev.jorel.commandapi.commandsenders.BukkitEntity;
+import dev.jorel.commandapi.commandsenders.BukkitFeedbackForwardingCommandSender;
+import dev.jorel.commandapi.commandsenders.BukkitNativeProxyCommandSender;
+import dev.jorel.commandapi.commandsenders.BukkitPlayer;
+import dev.jorel.commandapi.commandsenders.BukkitProxiedCommandSender;
+import dev.jorel.commandapi.commandsenders.BukkitRemoteConsoleCommandSender;
 import dev.jorel.commandapi.exceptions.WrapperCommandSyntaxException;
 import dev.jorel.commandapi.nms.NMS;
 import dev.jorel.commandapi.preprocessor.RequireField;
@@ -329,56 +356,70 @@ void updateHelpForCommands(List<RegisteredCommand> commands) {
 		Map<String, HelpTopic> helpTopicsToAdd = new HashMap<>();
 
 		for (RegisteredCommand command : commands) {
-			// Generate short description
+			// Don't override the plugin help topic
+			String commandPrefix = generateCommandHelpPrefix(command.commandName());
+			StringBuilder aliasSb = new StringBuilder();
 			final String shortDescription;
-			final Optional<String> shortDescriptionOptional = command.shortDescription();
-			final Optional<String> fullDescriptionOptional = command.fullDescription();
-			if (shortDescriptionOptional.isPresent()) {
-				shortDescription = shortDescriptionOptional.get();
-			} else if (fullDescriptionOptional.isPresent()) {
-				shortDescription = fullDescriptionOptional.get();
+			
+			// Must be empty string, not null as defined by OBC::CustomHelpTopic
+			final String permission = command.permission().getPermission().orElse("");
+			
+			HelpTopic helpTopic;
+			if (command.helpTopic().isPresent()) {
+				helpTopic = (HelpTopic) command.helpTopic().get();
+				shortDescription = "";
 			} else {
-				shortDescription = "A command by the " + config.getPlugin().getName() + " plugin.";
-			}
-
-			// Generate full description
-			StringBuilder sb = new StringBuilder();
-			if (fullDescriptionOptional.isPresent()) {
-				sb.append(ChatColor.GOLD).append("Description: ").append(ChatColor.WHITE).append(fullDescriptionOptional.get()).append("\n");
-			}
-
-			generateHelpUsage(sb, command);
-			sb.append("\n");
+				// Generate short description
+				final Optional<String> shortDescriptionOptional = command.shortDescription();
+				final Optional<String> fullDescriptionOptional = command.fullDescription();
+				if (shortDescriptionOptional.isPresent()) {
+					shortDescription = shortDescriptionOptional.get();
+				} else if (fullDescriptionOptional.isPresent()) {
+					shortDescription = fullDescriptionOptional.get();
+				} else {
+					shortDescription = "A command by the " + config.getPlugin().getName() + " plugin.";
+				}
+	
+				// Generate full description
+				StringBuilder sb = new StringBuilder();
+				if (fullDescriptionOptional.isPresent()) {
+					sb.append(ChatColor.GOLD).append("Description: ").append(ChatColor.WHITE).append(fullDescriptionOptional.get()).append("\n");
+				}
+	
+				generateHelpUsage(sb, command);
+				sb.append("\n");
+	
+				// Generate aliases. We make a copy of the StringBuilder because we
+				// want to change the output when we register aliases
+				aliasSb = new StringBuilder(sb.toString());
+				if (command.aliases().length > 0) {
+					sb.append(ChatColor.GOLD).append("Aliases: ").append(ChatColor.WHITE).append(String.join(", ", command.aliases()));
+				}
 
-			// Generate aliases. We make a copy of the StringBuilder because we
-			// want to change the output when we register aliases
-			StringBuilder aliasSb = new StringBuilder(sb.toString());
-			if (command.aliases().length > 0) {
-				sb.append(ChatColor.GOLD).append("Aliases: ").append(ChatColor.WHITE).append(String.join(", ", command.aliases()));
+				helpTopic = generateHelpTopic(commandPrefix, shortDescription, sb.toString().trim(), permission);
 			}
-
-			// Must be empty string, not null as defined by OBC::CustomHelpTopic
-			String permission = command.permission().getPermission().orElse("");
-
-			// Don't override the plugin help topic
-			String commandPrefix = generateCommandHelpPrefix(command.commandName());
-			helpTopicsToAdd.put(commandPrefix, generateHelpTopic(commandPrefix, shortDescription, sb.toString().trim(), permission));
+			helpTopicsToAdd.put(commandPrefix, helpTopic);
 
 			for (String alias : command.aliases()) {
-				StringBuilder currentAliasSb = new StringBuilder(aliasSb.toString());
-				currentAliasSb.append(ChatColor.GOLD).append("Aliases: ").append(ChatColor.WHITE);
-
-				// We want to get all aliases (including the original command name),
-				// except for the current alias
-				List<String> aliases = new ArrayList<>(Arrays.asList(command.aliases()));
-				aliases.add(command.commandName());
-				aliases.remove(alias);
-
-				currentAliasSb.append(ChatColor.WHITE).append(String.join(", ", aliases));
-
-				// Don't override the plugin help topic
-				commandPrefix = generateCommandHelpPrefix(alias);
-				helpTopicsToAdd.put(commandPrefix, generateHelpTopic(commandPrefix, shortDescription, currentAliasSb.toString().trim(), permission));
+				if (command.helpTopic().isPresent()) {
+					helpTopic = (HelpTopic) command.helpTopic().get();
+				} else {
+					StringBuilder currentAliasSb = new StringBuilder(aliasSb.toString());
+					currentAliasSb.append(ChatColor.GOLD).append("Aliases: ").append(ChatColor.WHITE);
+	
+					// We want to get all aliases (including the original command name),
+					// except for the current alias
+					List<String> aliases = new ArrayList<>(Arrays.asList(command.aliases()));
+					aliases.add(command.commandName());
+					aliases.remove(alias);
+	
+					currentAliasSb.append(ChatColor.WHITE).append(String.join(", ", aliases));
+	
+					// Don't override the plugin help topic
+					commandPrefix = generateCommandHelpPrefix(alias);
+					helpTopic = generateHelpTopic(commandPrefix, shortDescription, currentAliasSb.toString().trim(), permission);
+				}
+				helpTopicsToAdd.put(commandPrefix, helpTopic);
 			}
 		}