refactor for a simpler annotation set

Author: HSGamer

README.md

@@ -1,16 +1,11 @@
 # CraftCommand
 
-An opinionated annotation-driven command framework for Java applications.
-
-## Difference from other frameworks
-
-The only difference is that while others rely on runtime reflection to fetch and handle annotations, 
-this framework constructs the native code with annotation processor and JavaPoet, 
-allows near native speed with minimal reflection usage.
+Compile-time command framework for Java. Generates platform-specific wrappers via annotation processing — no runtime
+reflection for execution.
 
 ## Installation
 
-It is recommended to import `craftcommand-bom` in your `<dependencyManagement>` section to manage version configurations of CraftCommand modules:
+Use the BOM for version management:
 
 ```xml
 <dependencyManagement>
@@ -26,7 +21,7 @@ It is recommended to import `craftcommand-bom` in your `<dependencyManagement>`
 </dependencyManagement>
 ```
 
-Then, add the annotation and runtime dependency to your `pom.xml` without specifying a version:
+Add annotations + runtime + processor:
 
 ```xml
 <dependency>
@@ -39,8 +34,6 @@ Then, add the annotation and runtime dependency to your `pom.xml` without specif
 </dependency>
 ```
 
-And configure the annotation processor in your compiler plugin:
-
 ```xml
 <plugin>
     <groupId>org.apache.maven.plugins</groupId>
@@ -57,51 +50,44 @@ And configure the annotation processor in your compiler plugin:
 </plugin>
 ```
 
-## Quick Start (Standalone Console App)
-
-### 1. Define your Command Class
+## Quick Start
 
 ```java
-package myapp;
-
-import io.github.projectunified.craftcommand.annotation.*;
-
-@Command(value = "calc", description = "Simple Calculator Command")
+@Command("calc")
 public class CalculatorCommand {
 
     @Default
-    public void defaultAction(Object sender) {
-        System.out.println("Use /calc add <num1> <num2>");
+    public void execute(Object sender) {
+        System.out.println("Use /calc add <a> <b>");
     }
 
-    @Subcommand(value = "add", aliases = {"sum"})
-    public void add(Object sender, 
-                    @Min(value = 0, message = "Inputs must be positive") double a, 
-                    double b) {
+    @Command(value = "add", aliases = {"sum"})
+    public void add(Object sender, double a, double b) {
         System.out.println("Result: " + (a + b));
     }
 }
 ```
 
-### 2. Register & Execute in your App
-
 ```java
-import io.github.projectunified.craftcommand.standalone.StandaloneCommandManager;
-import io.github.projectunified.craftcommand.standalone.StandaloneCommand;
-
-public class Main {
-    public static void main(String[] args) {
-        StandaloneCommandManager manager = new StandaloneCommandManager();
-        
-        // Register the annotated command instance
-        manager.register(new CalculatorCommand());
-        
-        // Customizing translation keys/messages in the dictionary
-        manager.setMessage("validation.min", "Error: %s cannot be less than %s!");
-        
-        // Execute the command
-        StandaloneCommand cmd = manager.getCommand("calc");
-        cmd.execute("sender", new String[]{"add", "5.2", "10.0"}); // Prints: Result: 15.2
-    }
-}
+StandaloneCommandManager manager = new StandaloneCommandManager();
+manager.register(new CalculatorCommand());
+
+StandaloneCommand cmd = manager.getCommand("calc");
+cmd.execute("sender", new String[]{"add", "5", "10"}); // Result: 15.0
 ```
+
+## Supported Platforms
+
+| Platform          | Runtime                           | Processor                            |
+|-------------------|-----------------------------------|--------------------------------------|
+| Bukkit/Spigot     | `craftcommand-bukkit-runtime`     | `craftcommand-bukkit-processor`      |
+| Paper (Brigadier) | `craftcommand-paper-runtime`      | `craftcommand-paper-processor`       |
+| Paper (Basic)     | `craftcommand-paper-runtime`      | `craftcommand-paper-processor-basic` |
+| Standalone        | `craftcommand-standalone-runtime` | `craftcommand-standalone-processor`  |
+
+## Documentation
+
+- [Annotations Reference](docs/annotations.md)
+- [Architecture](docs/architecture.md)
+- [Processor Flow](docs/processor-flow.md)
+- [Platform Tutorials](docs/platform-tutorials.md)

annotations/src/main/java/io/github/projectunified/craftcommand/annotation/Command.java

@@ -6,30 +6,27 @@
 import java.lang.annotation.Target;
 
 /**
- * Annotation used to define a main command.
- * Apply this to a class to mark it as a command entry point.
+ * Defines a command or subcommand.
+ *
+ * <p>On a class: marks it as the main command entry point.
+ * On a method or nested class: marks it as a subcommand.
  */
-@Target(ElementType.TYPE)
+@Target({ElementType.TYPE, ElementType.METHOD})
 @Retention(RetentionPolicy.CLASS)
 public @interface Command {
     /**
-     * The primary name of the command.
-     *
-     * @return the command name
+     * Command or subcommand name.
      */
     String value();
 
     /**
-     * The aliases of the command.
-     *
-     * @return the command aliases
+     * Alternative names for this command.
      */
     String[] aliases() default {};
 
     /**
-     * The description of the command.
-     *
-     * @return the command description
+     * Command description. Prefix with {@code i18n:} for runtime i18n lookup.
+     * e.g. {@code "Static text"} or {@code "i18n:commands.cmd.desc"}.
      */
     String description() default "";
 }

annotations/src/main/java/io/github/projectunified/craftcommand/annotation/Default.java

@@ -6,10 +6,18 @@
 import java.lang.annotation.Target;
 
 /**
- * Annotation used to define the default command action when no subcommands are matched.
- * Apply this to a method within a command class.
+ * Dual-purpose annotation.
+ *
+ * <p><b>On methods:</b> Marks the default action when no subcommand matches.
+ * {@link #value()} must be empty.
+ *
+ * <p><b>On parameters:</b> Marks as optional. {@link #value()} is the default value string.
  */
-@Target(ElementType.METHOD)
+@Target({ElementType.METHOD, ElementType.PARAMETER})
 @Retention(RetentionPolicy.CLASS)
 public @interface Default {
+    /**
+     * Default value string for optional parameters. Empty on methods.
+     */
+    String value() default "";
 }

annotations/src/main/java/io/github/projectunified/craftcommand/annotation/Greedy.java

@@ -6,8 +6,7 @@
 import java.lang.annotation.Target;
 
 /**
- * Annotation indicating that a parameter consumes all remaining command arguments.
- * Apply this to the last parameter of a command method.
+ * Makes a parameter consume all remaining arguments. Must be the last parameter.
  */
 @Target(ElementType.PARAMETER)
 @Retention(RetentionPolicy.CLASS)

annotations/src/main/java/io/github/projectunified/craftcommand/annotation/Name.java

@@ -6,16 +6,13 @@
 import java.lang.annotation.Target;
 
 /**
- * Annotation used to define a custom name for a command parameter.
- * This name will be displayed in command usages and exception messages.
+ * Overrides the parameter name in usage strings and error messages.
  */
 @Target(ElementType.PARAMETER)
 @Retention(RetentionPolicy.CLASS)
 public @interface Name {
     /**
-     * The custom name of the parameter.
-     *
-     * @return the parameter name
+     * The display name.
      */
     String value();
 }

annotations/src/main/java/io/github/projectunified/craftcommand/annotation/Optional.java

@@ -6,19 +6,16 @@
 import java.lang.annotation.Target;
 
 /**
- * Declares a local resolver method inside a command class, or binds a parameter to one.
- * When placed on a method, it marks it as a resolver.
- * When placed on a parameter, it binds the parameter to a specific resolver by name.
+ * Binds a parameter to a local resolver method, or marks a method as a resolver.
+ *
+ * <p>On a method: declares it as a resolver for its return type.
+ * On a parameter: binds to a resolver by name (value).
  */
 @Target({ElementType.METHOD, ElementType.PARAMETER})
 @Retention(RetentionPolicy.CLASS)
 public @interface Resolve {
     /**
-     * The name of the resolver.
-     * If placed on a method, this specifies an optional name to reference this resolver.
-     * If placed on a parameter, this specifies the name of the resolver method to bind to.
-     *
-     * @return the resolver name
+     * Resolver method name. Optional on methods, required on parameters.
      */
     String value() default "";
 }

annotations/src/main/java/io/github/projectunified/craftcommand/annotation/Resolve.java

@@ -6,16 +6,13 @@
 import java.lang.annotation.Target;
 
 /**
- * Binds a command parameter to a suggestion provider method inside the command class.
- * This method is invoked when tab completing arguments for the parameter.
+ * Binds a parameter to a suggestion provider method in the command class.
  */
 @Target(ElementType.PARAMETER)
 @Retention(RetentionPolicy.CLASS)
 public @interface Suggest {
     /**
-     * The name of the suggestion provider method inside the command class.
-     *
-     * @return the suggestion provider method name
+     * Name of the suggestion provider method.
      */
     String value();
 }

annotations/src/main/java/io/github/projectunified/craftcommand/annotation/Subcommand.java

@@ -1,12 +1,8 @@
 /**
- * Annotations used to define commands with CraftCommand.
+ * Core annotations for defining commands with CraftCommand.
  *
- * <p>Primary annotations:
- * <ul>
- *   <li>{@link io.github.projectunified.craftcommand.annotation.Command} — marks a class as a command</li>
- *   <li>{@link io.github.projectunified.craftcommand.annotation.Subcommand} — marks a method as a subcommand</li>
- *   <li>{@link io.github.projectunified.craftcommand.annotation.Default} — marks a method as the default executor</li>
- *   <li>{@link io.github.projectunified.craftcommand.annotation.Resolve} — marks a method as a parameter resolver</li>
- * </ul>
+ * @see io.github.projectunified.craftcommand.annotation.Command
+ * @see io.github.projectunified.craftcommand.annotation.Default
+ * @see io.github.projectunified.craftcommand.annotation.Resolve
  */
 package io.github.projectunified.craftcommand.annotation;