feature: document cloud-annotations

docs/annotations/index.md

@@ -1 +1,181 @@
 # cloud-annotations
+
+The annotations module offers a different way of creating commands, parsers, suggestion providers and exception
+handlers by using annotated methods.
+
+The module can also function as an [annotation processor](#annotation-processing) which has some added benefits.
+
+There are extensions to `cloud-annotations` for Kotlin, more information [here](../kotlin/annotations.md).
+
+## Installation
+
+Cloud Annotations is available through [Maven Central](https://search.maven.org/search?q=cloud.commandframework).
+
+<!-- prettier-ignore -->
+=== "Maven"
+
+    ```xml
+    <dependencies>
+        <dependency>
+            <groupId>cloud.commandframework</groupId>
+            <artifactId>cloud-annotations</artifactId>
+            <version>dCLOUD_BASE_VERSIONd</version>
+        </dependency>
+    </dependencies>
+
+    <!-- Optional -->
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <annotationProcessorPaths>
+                        <path>
+                            <groupId>cloud.commandframework</groupId>
+                            <artifactId>cloud-annotations</artifactId>
+                            <version>dCLOUD_BASE_VERSIONd</version>
+                        </path>
+                    </annotationProcessorPaths>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+    ```
+
+=== "Gradle (Kotlin)"
+
+    ```kotlin
+    implementation("cloud.commandframework:cloud-annotations:dCLOUD_BASE_VERSIONd")
+    // Optional:
+    annotationProcessor("cloud.commandframework:cloud-annotations:dCLOUD_BASE_VERSIONd")
+    ```
+
+=== "Gradle (Groovy)"
+
+    ```groovy
+    implementation 'cloud.commandframework:cloud-annotations:dCLOUD_BASE_VERSIONd'
+    // Optional:
+    annotationProcessor 'cloud.commandframework:cloud-annotations:dCLOUD_BASE_VERSIONd'
+    ```
+
+You then need to create an `AnnotationParser` instance.
+When creating the annotation parser you can supply an optional
+function that maps parser parameters to [command meta](../core/index.md#command-meta), these
+parameters can be set using [annotation mappers](#annotation-mappers) and allow you to map annotations
+to meta values.
+
+```java title="Creating an annotation parser"
+// Parser without a CommandMeta mapper.
+AnnotationParser<C> annotationParser = new AnnotationParser(commandManager);
+
+// Parser with a CommandMeta mapper.
+AnnotationParser<C> annotationParser = new AnnotationParser(
+    commandManager,
+    parameters -> CommandMeta.empty()
+);
+```
+
+To parse & register the different annotated methods you simply invoke `AnnotationParser.parse` with an
+instance of the class that you wish to parse.
+
+## Command Methods
+
+Command methods are annotated methods that are used to construct and handle commands.
+The method has to be annotated with a `@CommandMethod` annotation that specifies the command
+syntax.
+The parsed command components are mapped to the method parameters.
+The parameters may also be mapped to [injected](#injections) values, such as the command sender instance,
+the `CommandContext` or custom injections.
+
+The annotation may be repeated in order to generate multiple commands from the same method.
+
+### Syntax
+
+There are three different parts that make up the command syntax:
+
+- **Literals**: `literal`, `literal|alias`
+- **Required variable components**: `<variable>`
+- **Optional variable components**: `[variable]`
+
+Examples:
+
+- `@CommandMethod("command <string> [int]")`
+- `@CommandMethod("command <string> literal|alias [int]")`
+
+The ordering of the method parameters does not matter, the command structure is entirely determined from the
+syntax string.
+
+The types of the variable components are determined from the method parameters.
+
+### Command Components
+
+`@Argument` annotations on method parameters is used to map the method parameter to the corresponding syntax fragment.
+
+If you compile with the `-parameters` compiler option then you do not need to specify the name in the annotation and
+it will instead be inferred from the parameter name (though you can override it if you want to).
+You may also choose not to add the annotation at all.
+
+The argument annotation also allows you to specify non-default parsers and suggestion providers.
+You may specify the argument description through the annotation as well.
+
+```java
+@CommandMethod("command <required> [optional]")
+public void yourCommand(
+  @Argument(value = "required", description = "A string") String string, // Uses a name override!
+  @Nullable String optional // Name is inferred, and so is @Argument!
+) {
+  // ...
+}
+```
+
+#### Default values
+
+[Default values](../core/index.md#optional) can be specified using the `@DefaultValue` annotation.
+These values will always be parsed:
+
+```java
+@DefaultValue("foo") @Argument String string
+```
+
+### Descriptions
+
+`@CommandMethod` can be added to an annotated command method to set the command description.
+
+You can override how the descriptions are mapped by setting replacing the description mapper:
+
+```java
+annotationParser.descriptionMapper(string -> Description.of("blablabla " + string));
+```
+
+### Permissions
+
+`@CommandPermission` can be added to a command method to set the command permission.
+Only simple string-permissions can be used.
+You may use a [builder modifier](#builder-modifiers) to do more complex mappings.
+
+### Proxies
+
+`@ProxiedBy` can be used to generate a command proxy.
+
+## Parsers
+
+## Suggestion Providers
+
+## Exception Handlers
+
+## Injections
+
+## Customization
+
+### Builder Decorators
+
+### Builder Modifiers
+
+### Annotation Mappers
+
+### Pre-processor mappers
+
+## Annotation Processing
+
+### Command Containers

mkdocs.yml

@@ -89,11 +89,11 @@ plugins:
   - git-revision-date-localized:
       enable_creation_date: false
       fallback_to_build_date: true
-extra:
-  consent:
-    title: Cookie consent
-    description: >-
-      We use cookies to recognize your repeated visits and preferences, as well
-      as to measure the effectiveness of our documentation and whether users
-      find what they're searching for. With your consent, you're helping us to
-      make our documentation better.
+#extra:
+#  consent:
+#    title: Cookie consent
+#    description: >-
+#      We use cookies to recognize your repeated visits and preferences, as well
+#      as to measure the effectiveness of our documentation and whether users
+#      find what they're searching for. With your consent, you're helping us to
+#      make our documentation better.