docs: add more docs\!

Author: yusshu

docs/annotated/annotated.md

@@ -0,0 +1,13 @@
+## Annotated Commands
+
+`command-flow` allows developers to create full command trees in a declarative way
+using annotated classes and methods.
+
+The annotated command API is just an alternative way to create `Command` instances,
+we use this instead of the classic `Command.builder(String)` method.
+
+### Elements of the Annotated Command API
+
+The annotated command API is composed of 3 elements:
+- The `@Command` annotation and others.
+- The `AnnotatedCommandTreeBuilder` interface

docs/annotated/command-class.md

@@ -0,0 +1,78 @@
+## Command Class
+
+The annotated command API has a `CommandClass` interface used to mark a class as a container
+of commands or a command itself.
+
+To declare the commands, we use annotations:
+
+<!--@formatter:off-->
+```java
+@Command(names = "teleport")
+public class TeleportCommand implements CommandClass {
+    
+    @Command(names = "") // empty name indicates the root command
+    public void run(
+            @Sender Player sender, // the sender player
+            Player target          // the target player (argument)
+    ) {
+        sender.teleport(target);
+    } 
+    
+}
+```
+<!--@formatter:on-->
+
+In this example we have created a `/teleport` command that takes a player name
+as an argument *(command-flow will parse it and find the right Player)* and
+teleports the sender to the target player.
+
+The `@Command` annotation is used to mark a method as a command, it can be used
+on methods inside a `CommandClass` or on the class itself.
+
+See this other example:
+
+<!--@formatter:off-->
+```java
+@Command(names = { "friends", "friend", "f", "fr" }) // name, ...aliases
+public class FriendsCommand implements CommandClass {
+    
+    @Command(names = "add")
+    public void add(@Sender Player sender, Player target) {
+        // add 'target' to 'sender' friend list
+    }
+    
+    @Command(names = "remove")
+    public void remove(@Sender Player sender, Player target) {
+        // remove 'target' from 'sender' friend list
+    }
+    
+    @Command(names = "list")
+    public void list(@Sender Player sender) {
+        // list all 'sender' friends and show
+    }
+    
+    @Command(names = "broadcast")
+    public void broadcast(@Sender Player sender, @Text String message) {
+        // send 'message' to all the friends of 'sender'
+    }
+    
+}
+```
+<!--@formatter:on-->
+
+In this example we have created a `/friends` command with 4 subcommands:
+- `/friends add <player>`: add a player to the sender friend list.
+- `/friends remove <player>`: remove a player from the sender friend list.
+- `/friends list`: list all the sender friends.
+- `/friends broadcast <...message>`: send a message to all the sender friends.
+
+In this new example we also see these new stuff:
+- `@Command(names = {...})`: multiple names! The first one is considered the actual
+command name and the rest are aliases.
+- `@Text`: used to mark a parameter as a text argument, this means that it will
+consume all the arguments left in the command and join them with spaces.
+
+### Registering them
+
+To register command classes we must convert them to `Command` first, we can do
+that using the `AnnotatedCommandTreeBuilder` interface, check the next page!

docs/annotated/command-tree-builder.md

@@ -0,0 +1,35 @@
+## Command Builder
+
+The `AnnotatedCommandTreeBuilder` is the interface responsible for building `Command`
+instances from annotated commands and classes.
+
+### Creating an AnnotatedCommandTreeBuilder
+
+To create a `AnnotatedCommandTreeBuilder` we must create a `PartInjector` first and
+*(optionally)* a `SubCommandInstanceCreator`. More about this in the next pages.
+
+```java
+PartInjector injector = ...;
+SubCommandInstanceCreator instanceCreator = ...;
+
+AnnotatedCommandTreeBuilder builder = AnnotatedCommandTreeBuilder.create(injector, instanceCreator);
+```
+
+### Building a Command
+
+Now that we have a `AnnotatedCommandTreeBuilder` we can build a command (or multiple commands).
+To do this we must call the `fromClass` method with the class of the command we want to build.
+
+Note that this method returns a list of commands, since a single class may contain multiple
+root commands on it.
+
+```java
+// create the builder
+AnnotatedCommandTreeBuilder builder = ...;
+
+// build the Command list from our class
+List<Command> commands = builder.fromClass(MyCommand.class);
+
+// now we can register them using the CommandManager#registerCommands convenience method
+commandManager.registerCommands(commands);
+```

docs/annotated/index.txt

@@ -0,0 +1,5 @@
+annotated.md
+command-class.md
+command-tree-builder.md
+part-injector.md
+subcommand-instance-creator.md

docs/annotated/part-injector.md

@@ -0,0 +1,34 @@
+## Part Injector
+
+The `PartInjector` is a registry which holds the registered PartFactories
+and PartModifiers.
+
+- A `PartFactory` is a class that provides a way to create an specific type of part.
+- A `PartModifier` is like a PartFactory, the difference is that it may wrap the original part  
+  or modify it instead of creating a new one.
+
+### Creating a PartInjector
+
+Creating a `PartInjector` is simple, just do the following:
+
+```java
+PartInjector partInjector = PartInjector.create();
+
+// install the default bindings!
+// parts for native and core types like String, Boolean, Double, Float, Integer,
+// Text(String), ArgumentStack, CommandContext, also modifiers like LimitModifier,
+// OptionalModifier, ValueFlagModifier
+partInjector.install(new DefaultsModule());
+```
+
+### Platform Specific
+
+Some of the platform-specific subprojects include a `Module` for the `PartInjector`
+that can be easily installed to obtain the default bindings for that platform.
+
+For example, for Bukkit (`commandflow-bukkit` subproject):
+```java
+// install bindings for the default bindings for Bukkit, such as
+//  CommandSender, OfflinePlayer, Player, World, GameMode and @Sender Player
+partInjector.install(new BukkitModule());
+```

docs/annotated/subcommand-instance-creator.md

@@ -0,0 +1,53 @@
+## SubCommand Instantiation
+
+Sometimes we have a command that has subcommands declared with the `@SubCommandClasses`
+annotation. In this case, the command framework needs to know how to instantiate the
+subcommands.
+
+We can specify how to instantiate the subcommands by implementing the `SubCommandInstanceCreator`
+interface.
+
+### The `SubCommandInstanceCreator` interface
+
+Functional interface that has a single method `createInstance(Class<? extends CommandClass>, CommandClass)`,
+that receives the subcommand class and its parent instance, and returns the sub command instance.
+
+If we do not specify one, the annotated command tree builder will instantiate the subcommand
+using Reflection, by looking for constructor that accepts the parent's class as the single
+parameter an empty constructor.
+
+The `SubCommandInstanceCreator` is set to the `AnnotatedCommandTreeBuilder` when instantiating
+it, for example:
+
+<!--@formatter:off-->
+```java
+// will use the default SubCommandInstanceCreator
+AnnotatedCommandTreeBuilder commandBuilder = AnnotatedCommandTreeBuilder.create(partInjector);
+
+// will use a custom SubCommandInstanceCreator
+AnnotatedCommandTreeBuilder commandBuilder = AnnotatedCommandTreeBuilder.create(
+        partInjector,
+        new MyCustomSubCommandInstanceCreator()
+);
+```
+<!--@formatter:on-->
+
+### Common Implementations
+
+It is common for `command-flow` to be used along with dependency injection frameworks, so
+you can just create a `SubCommandInstanceCreator` that does the following:
+
+**For [Google's Guice](https://github.com/google/guice) or [Unnamed Team's inject](https://github.com/unnamed/inject):**
+```java
+// obtain the Injector instance
+Injector injector = ...;
+
+// create the SubCommandInstanceCreator
+SubCommandInstanceCreator subCommandCreator = (clazz, parent) -> injector.getInstance(clazz);
+
+// now set it when creating an AnnotatedCommandTreeBuilder
+AnnotatedCommandTreeBuilder commandBuilder = AnnotatedCommandTreeBuilder.create(
+        partInjector,
+        subCommandCreator
+);
+```

docs/concepts/command-context.md

@@ -0,0 +1,5 @@
+## Command Context
+
+A mutable object which contains the context for a command execution, including but not
+limited to the values for every parsed part, the raw arguments list and the raw arguments
+for every part, the labels and the Command execution path (which path of subcommands was taken).

docs/concepts/command-manager.md

@@ -0,0 +1,43 @@
+## Command Manager
+
+The CommandManager manages the command registration, parsing and execution. Also provides
+a way to obtain command suggestions *(which can be used for tab-completion in programs like
+CLI applications or Minecraft plugins)* for a given input.
+
+### Creating a Command Manager
+
+Depending on your platform, you may want to use a different implementation of the
+`CommandManager`. Check your [platform](../platforms/platforms.md)'s documentation
+to get more information.
+
+However, there is a default implementation called `SimpleCommandManager` which can be
+used in any platform, but it doesn't provide any implementation-specific features.
+
+<!--@formatter:off-->
+```java
+CommandManager commandManager = new SimpleCommandManager();
+```
+<!--@formatter:on-->
+
+### Registering commands
+
+To register a command, you need to create a `Command` object and register it using
+the `CommandManager.registerCommand(Command)` method.
+
+<!--@formatter:off-->
+```java
+// create CommandManager
+CommandManager manager = ...;
+
+// create Command using builder
+Command command = Command.builder("test")
+        .description("A test command")
+        .action(context -> {
+            System.out.println("Hello world!");
+        })
+        .build();
+
+// register the command
+manager.registerCommand(command);
+```
+<!--@formatter:on-->

docs/concepts/command-part.md

@@ -0,0 +1,10 @@
+## Command Part
+
+This is the second most fundamental component, it can be understood as every argument
+of a [Command](./command.md), including things like subcommands, flags, non positional
+arguments, etc.
+
+It can use arguments from the argument list, or provide them using any other means. They
+can also forward the parsing responsibility to another part and just act as a modifier.
+
+Most of the default parts can be found at the `Parts` class.

docs/concepts/command.md

@@ -0,0 +1,19 @@
+## Command
+
+Commands are the most fundamental component of the framework. It contains all the
+information related to a command, included but not limited to name, aliases, permission,
+parts, etc.
+
+Commands are created using the `Command.builder(String)` method, which returns an
+`Command.Builder` instance where you can set all the information of the command.
+
+Example:
+<!--@formatter:off-->
+```java
+Command command = Command.builder("Test")
+        .action(context -> {
+            System.out.println("Hi!");
+        })
+        .build();
+```
+<!--@formatter:on-->

docs/concepts/index.txt

@@ -0,0 +1,4 @@
+command.md
+command-manager.md
+command-part.md
+command-context.md

docs/getting-started.md

@@ -2,24 +2,22 @@
 
 Welcome to the `command-flow` documentation
 
-CommandFlow is a flexible command framework which removes lots of
-boilerplate code used in commands
-
-The command framework is divided into two parts. One is the actual
-command framework and the other one is the API to allow creation of
-a complete command tree based on annotations
-
-### Components of the Command Framework
-
-There are some basic components that you should at least be aware of to use **CommandFlow**
-- **Command:** This is the most fundamental component, the **Command**. It contains all the information related to a command, included but not limited to name, aliases, permission, parts, etc.
-  Those are created using the `Command.builder(String)` method, which returns an `Command.Builder` instance where you can set all the information of the command.
-
-- **CommandPart:** This is the second most fundamental component, it can be understood as every argument of a **Command**, including things like subcommands, flags, non positional arguments, etc. It can use arguments from the argument list, or provide them using any other means also they can forward the parsing to another part and just act as a modifier. Most of the default parts can be found at the class `Parts`
-
-- **CommandContext**: This is a mutable object which contains the context for the called command including but not limited to the values for every part parsed, the raw arguments list and the raw arguments for every part, the labels and the Command execution path(which path of subcommands was taken).
-
-
-### Known bugs or misbehaviours
-The next list are the known bugs that must be resolved at some point:
-- No known bugs at the moment.
+`command-flow` is a flexible and platform-agnostic command framework
+for Java. With this framework you can *imperatively* create command trees
+using builders or *declaratively* using annotated classes and methods.
+
+See the following example:
+```java
+@Command("test")
+public class TestCommand implements CommandClass {
+    
+    @Command("hello")
+    public void hello(CommandSender sender) {
+        sender.sendMessage("Hello World!");
+    }
+    
+}
+```
+
+### Features
+- Easily create commands using builders or annotations

docs/index.txt

@@ -1,2 +1,5 @@
 getting-started.md
-installation.md
+installation.md
+concepts
+annotated
+platforms

docs/platforms/brigadier.md

@@ -0,0 +1 @@
+## Bukkit with Brigadier

docs/platforms/bukkit.md

@@ -0,0 +1 @@
+## Bukkit

docs/platforms/bungeecord.md

@@ -0,0 +1 @@
+## BungeeCord

docs/platforms/discord-jda.md

@@ -0,0 +1 @@
+## Discord (JDA)

docs/platforms/index.txt

@@ -0,0 +1 @@
+platforms.md