feat: annotation-based commands part

Author: MC-XiaoHei

docs/en/annotations/annotations.md

@@ -0,0 +1,124 @@
+---
+order: 2
+authors:
+  - JorelAli
+---
+
+# Annotations
+
+This page outlines in detail the list of all annotations that the CommandAPI's annotation-based command system includes.
+
+## Annotations that go on classes
+
+### `@Command("commandName")`
+
+The `@Command` annotation is used to declare a command. The parameter is the name of the command that will be registered.
+
+<<< @/../reference-code/src/main/java/annotations/Intro.java#declareCommand
+
+### `@Alias({...})`
+
+The `@Alias` annotation is used to declare a list of aliases for a command. The parameter is a list of aliases which can be used for the command.
+
+<<< @/../reference-code/src/main/java/annotations/Annotations.java#aliasClassExample
+
+### `@Permission("permissionNode")`
+
+The `@Permission` annotation is used to add a permission node to a command. Users that want to run this command must have this permission. The parameter is the permission node required to run the command.
+
+<<< @/../reference-code/src/main/java/annotations/Annotations.java#permissionClassExample
+
+### `@NeedsOp`
+
+The `@NeedsOp` annotation is used to indicate that a command needs to have operator privileges to run it. This annotation has no parameters.
+
+<<< @/../reference-code/src/main/java/annotations/Annotations.java#needsOpClassExample
+
+### `@Help("Full description")`
+
+The `@Help` annotation is used to add a help topic to a command. This annotation can take two forms:
+
+A simple form which just uses a string which is used as the full description for a command:
+
+<<< @/../reference-code/src/main/java/annotations/Annotations.java#helpClassExample
+
+A form with two parameters `value` and `shortDescription`, to provide the full description (`value`) and short description (`shortDescription`) content for a command:
+
+<<< @/../reference-code/src/main/java/annotations/Annotations.java#shortHelpClassExample
+
+## Annotations that go on methods
+
+To use annotations on methods, **methods must be static**.
+
+### `@Default`
+
+The `@Default` annotation indicates that the method is _not_ a subcommand. This acts in a similar way to regular Bukkit commands. Commands with the `@Default` annotation can be used to run the main code when the command named with the `@Command` annotation is stated, such as the following:
+
+<<< @/../reference-code/src/main/java/annotations/Annotations.java#defaultMethodExample
+
+The `@Default` annotation does not mean that the command can't have arguments! Arguments can still be used and declared as shown:
+
+<<< @/../reference-code/src/main/java/annotations/Annotations.java#defaultWithArgsMethodExample
+
+### `@Subcommand`
+
+The `@Subcommand` simply tells the CommandAPI that the declared method is a subcommand. This acts in a similar way to the regular CommandAPI's `.withSubcommand()` method. The subcommand annotation can take in a single string which is the name of the subcommand:
+
+<<< @/../reference-code/src/main/java/annotations/Annotations.java#subcommandMethodExample
+
+Or, it can take in a list of strings which represent the _aliases_ that can also be used for the declared subcommand:
+
+<<< @/../reference-code/src/main/java/annotations/Annotations.java#subcommandAliasesMethodExample
+
+### `@Permission`
+
+The `@Permission` annotation can also be used on methods to indicate that a permission is required to execute a command.
+
+<<< @/../reference-code/src/main/java/annotations/Annotations.java#permissionMethodExample
+
+### `@NeedsOp`
+
+The `@NeedsOp` annotation can also be used on methods to indicate that the user must be an operator to run the command.
+
+## Annotations that go on parameters
+
+The annotations for arguments are really simple, there's just two things you need to know:
+
+- To use an annotation argument, just add the letter `A` (for 'annotation') at the beginning of it! For example:
+
+$$\begin{align}
+\texttt{StringArgument}&\xrightarrow{A}\texttt{@AStringArgument}\\\\
+\texttt{PlayerArgument}&\xrightarrow{A}\texttt{@APlayerArgument}\\\\
+\texttt{AdvancementArgument}&\xrightarrow{A}\texttt{@AAdvancementArgument}\\\\
+&\hspace{0.75em}\vdots
+\end{align}$$
+
+  For example, we use `@AStringArgument` to indicate that this command takes a `StringArgument` as its first parameter:
+
+<<< @/../reference-code/src/main/java/annotations/Annotations.java#simpleParameterExample
+
+- **The name of the argument (referred to as "nodeName" in the normal CommandAPI system) is the name of the variable assigned to the parameter.** In the above code, this means that the name of the argument is `warpName`.
+
+### Special argument annotations
+
+Certain argument annotations have extra parameters that can be supplied to provide additional customization:
+
+#### Numerical arguments
+
+The following numerical arguments can take both a `min` and `max` value. Both of these are completely optional. This indicates the range of values (inclusive) that is valid for this argument. For example:
+
+<<< @/../reference-code/src/main/java/annotations/Annotations.java#numericalParameterExample
+
+#### Literal arguments
+
+Both the `LiteralArgument` and `MultiLiteralArgument` can be used. When these are used, the name of the variable assigned to the parameter is _ignored_ and not used as the argument's name.
+
+For the `@ALiteralArgument` annotation, the parameter is the literal to be used for the command. For the `@AMultiLiteralArgument`, the parameter can be an array of multiple literals to use:
+
+<<< @/../reference-code/src/main/java/annotations/Annotations.java#literalParameterExample
+
+#### Other arguments
+
+The `LocationArgument`, `Location2DArgument`, `EntitySelectorArgument` and `ScoreHolderArgument` can all take an extra parameter in their constructors. As a result, the annotation-equivalent of these arguments also allow you to provide the parameter in the annotation:
+
+<<< @/../reference-code/src/main/java/annotations/Annotations.java#otherParameterExample

docs/en/annotations/intro.md

@@ -0,0 +1,101 @@
+---
+order: 1
+authors:
+  - JorelAli
+---
+
+# Annotation-based commands
+
+The CommandAPI also includes a very small lightweight annotation-based command framework. This works very differently compared to previous commands shown in this documentation and **it is less feature-rich than registering commands using the other methods.**
+
+In short, the CommandAPI's annotation-based system:
+
+- Has no runtime overhead compared to using the regular command registration system (unlike other annotation-based frameworks such as [ACF](https://github.com/aikar/commands)).
+- Reduces code bloat (to an extent).
+- Improves readability since commands are declared declaratively instead of imperatively.
+- Is not as powerful as the regular command registration system.
+
+:::info
+
+Currently, the annotation framework is in its infancy, so any suggestions or improvements are heavily appreciated!
+
+:::
+
+:::danger Developer's Note:
+
+As of the time of writing, annotation-based commands are **not** compatible with the Kotlin programming language! The CommandAPI does have the [Kotlin DSL](../kotlin-dsl/intro.md) instead, which is leaner, cleaner and provides a much more Kotliny experience!
+
+:::
+
+Before we go into too much detail, let's take a look at an example of what this annotation framework looks like, and compare this to the existing method.
+
+## Example: A warp command
+
+Let's say we're writing a plugin with the capability to create warps to places on the server. To do this, we'll make a simple command `/warp`, defined as follows:
+
+```mccmd
+/warp - Shows help
+/warp <warp> - Teleports a player to <warp>
+/warp create <name> - Creates a new warp <name> at the player's location
+```
+
+### Warp command (without annotations)
+
+Using the regular CommandAPI, this is one way we can create this command. In the code below, we use StringArguments to represent the warp names. To teleport to a warp, we also populate it with suggestions (deferred so it updates), and also use a subcommand to represent `/warp create`:
+
+<<< @/../reference-code/src/main/java/annotations/Intro.java#legacyExample
+
+Seems fairly straightforward, given everything else covered in this documentation. Now let's compare it to using annotations!
+
+### Warp command (with annotations)
+
+I think it's best to show the example and the explain it afterwards:
+
+<<< @/../reference-code/src/main/java/annotations/Intro.java#annotationsExample
+
+<<< @/../reference-code/src/main/java/annotations/Intro.java#annotationsRegisterExample
+
+As we can see, the code certainly _looks_ very different to the normal registration method. Let's take it apart piece by piece to see what exactly is going on here.
+
+#### Command declaration
+
+<<< @/../reference-code/src/main/java/annotations/Intro.java#declareCommand
+
+Firstly, we declare our command `warp`. To do this, we use the `@Command` annotation and simply state the name of the command in the annotation. This annotation is attached to the class `WarpCommand`, which indicates that the whole class `WarpCommand` will be housing our command.
+
+The annotation framework is designed in such a way that an entire command is represented by a single class. This provides a more modular approach to command declaration that allows you to easily contain the methods of a command in one location.
+
+#### Default command
+<<< @/../reference-code/src/main/java/annotations/Intro.java#defaultExample
+
+Here, declare the main command implementation using the `@Default` annotation. The `@Default` annotation informs the CommandAPI that the method it is attached to does not have any subcommands. This is effectively the same as registering a regular command without using `.withSubcommand()`.
+
+Here, we simply write what happens when no arguments are run (i.e. the user just runs `/warp` on its own). As such, we don't include any parameters to our method.
+
+#### Default command (again!)
+
+<<< @/../reference-code/src/main/java/annotations/Intro.java#anotherDefaultExample
+
+We also have a second `@Default` annotated method, which handles our `/warp <warp>` command. Because this isn't a subcommand (the warp to teleport to is not a subcommand, it's an argument), we still using the `@Default` annotation. In this method, we include an argument with this command by using the `@AStringArgument` annotation. This argument uses the `StringArgument` class, and the name of this argument is "warpName", which is extracted from the name of the variable. Simply put, **the Annotation for an argument is A** followed by the name of the argument. This is synonymous with using the following:
+
+```java
+new StringArgument("warp")
+```
+
+It's also very important to note the parameters for this method. The first parameter is a `Player` object, which represents our command sender. The CommandAPI's annotation system uses the fact that the command sender is a `Player` object and automatically ensures that anyone using the command must be a `Player`. In other words, non-players (such as the console or command blocks), would be unable to execute this command.
+
+The second argument is a `String` object, which represents the result of our argument "warp". The CommandAPI's annotation system can also infer the return type of the argument that is provided to it (in this case, a `StringArgument` will produce a `String`) and will automatically cast and provide the result to that parameter.
+
+#### Subcommand
+
+<<< @/../reference-code/src/main/java/annotations/Intro.java#subcommandExample
+
+Lastly, we declare a subcommand to allow us to run `/warp create <name>`. To do this, we simply use the `@Subcommand` annotation. In this example, we also apply a permission node that is required to run the command by using the `@Permission` annotation. The rest is fairly straight forward - we declare an argument, in this case it's another `StringArgument` , so we use `@AStringArgument` and then declare everything else in a similar fashion to the default command executor.
+
+#### Registering the command
+
+Registering the command is fairly simple and is a one liner:
+
+<<< @/../reference-code/src/main/java/annotations/Intro.java#annotationsRegisterExample
+
+This line can be placed in your `onEnable()` or `onLoad()` method like you were registering a normal command.

docs/en/annotations/registration.md

@@ -0,0 +1,25 @@
+---
+order: 3
+authors:
+  - JorelAli
+---
+
+# Registering annotation-based commands
+
+Registering annotation-based commands is _really_ simple. To do this, we use the following method, where `className` is the name of a class with a `@Command` annotation:
+
+```java
+CommandAPI.registerCommand(className)
+```
+
+::::tip Example: Registering a Warp command
+
+Say we have a simple command `/warp` that is defined as follows:
+
+<<< @/../reference-code/src/main/java/annotations/Intro.java#annotationsExample
+
+We can register this in our `onLoad()` method so we can use this command from within Minecraft functions:
+
+<<< @/../reference-code/src/main/java/annotations/Registration.java#registerCommand
+
+::::

reference-code/pom.xml

@@ -60,6 +60,20 @@
                     </execution>
                 </executions>
             </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <version>3.8.1</version>
+                <configuration>
+                    <annotationProcessorPaths>
+                        <path>
+                            <groupId>dev.jorel</groupId>
+                            <artifactId>commandapi-annotations</artifactId>
+                            <version>9.6.2-SNAPSHOT</version>
+                        </path>
+                    </annotationProcessorPaths>
+                </configuration>
+            </plugin>
         </plugins>
     </build>
 
@@ -104,6 +118,12 @@
             <artifactId>commandapi-bukkit-kotlin</artifactId>
             <version>${commandapi.version}</version>
         </dependency>
+        <dependency>
+            <groupId>dev.jorel</groupId>
+            <artifactId>commandapi-annotations</artifactId>
+            <version>${commandapi.version}</version>
+            <scope>provided</scope>
+        </dependency>
 
         <!-- Other -->
         <dependency>