feat: misc doc updates (#18)

Updates to existing pages.  ---- 📚 Documentation preview 📚: https://incendocloud--18.org.readthedocs.build/en/18/  --------- Co-authored-by: Jason Penilla <[email protected]>
Incendo · Jan 3, 2024 · 9f82bc9 · 9f82bc9
1 parent 4f1c8f5
commit 9f82bc9
Show file tree

Hide file tree

Showing 4 changed files with 22 additions and 10 deletions.
diff --git a/README.md b/README.md
@@ -16,7 +16,7 @@ $ python3 -m pip install -r docs/requirements.txt
 and then you may run MkDocs locally using
 
 ```shell
-$ mkdocs serve
+$ python3 -m mkdocs serve
 ```
 
 after which the docs will be available at `http://127.0.0.1:8000/`.

diff --git a/docs/annotations/index.md b/docs/annotations/index.md
@@ -196,18 +196,19 @@ Exceptions will be wrapped in `ArgumentParseResult.failure`.
 You may create [suggestion providers](../core/index.md#suggestions) from annotated methods by using the `@Suggestions`
 annotation.
 
-The parameters of the method must be `CommandContext<C> context, String input` but the return type can be an iterable
+The parameters of the method must be `CommandContext<C> context, String input`
+or `CommandContext<C> context, CommandInput input` but the return type can be an iterable
 (or stream) of suggestion objects, or strings.
 
 ```java title="Example signatures"
 @Suggestions("name")
-public List<String> suggestions(CommandContext<C> context, String input) { /* ... */ }
+public List<String> suggestions(CommandContext<C> context, CommandInput input) { /* ... */ }
 
 @Suggestions("name")
 public Stream<String> suggestions(CommandContext<C> context, String input) { /* ... */ }
 
 @Suggestions("name")
-public Set<Suggestion> suggestions(CommandContext<C> context, String input) { /* ... */ }
+public Set<Suggestion> suggestions(CommandContext<C> context, CommandInput input) { /* ... */ }
 
 @Suggestions("name")
 public Iterable<String> suggestions(CommandContext<C> context, String input) { /* ... */ }

diff --git a/docs/core/index.md b/docs/core/index.md
@@ -80,13 +80,14 @@ You may provide your own suggestions using a suggestion provider.
 ### Execution coordinators
 
 The execution coordinator is responsible for coordinating command parsing and execution.
-Cloud ships with two different command execution coordinators:
+You may create a simple execution coordinator by using `ExecutionCoordinator.simpleCoordinator()` which will not
+enforce any particular executor and both parsing and suggestion generation will take place on the calling
+thread unless the parser or suggestion provider redirects to another executor.
 
-- **SimpleCommandExecutionCoordinator**: Performs all actions on the calling thread.
-- **AsynchronousCommandExecutionCoordinator**: Uses an executor to dispatch the parsing and execution tasks.
-  You can change the default executor, and also force command parsing to take place on the calling thread.
-
-You may also create your own execution coordinator by implementing `CommandExecutionCoordinator`.
+You may also use `ExecutionCoordinator.asyncCoordinator()` to create an execution coordinator that will perform
+parsing and suggestion generation asynchronously. You may customize the asynchronous coordinator by using
+`ExecutionCoordinator.builder()` and supply different executors for different execution steps, or use
+`ExecutionCoordinator.coordinatorFor(Executor)` to supply an executor which is used at every execution step.
 
 ### Building a command
 
@@ -153,6 +154,15 @@ This is done by using the `Command.Builder.senderType(Class)` method.
 Cloud will make sure that the sender is of the right type when executing the command, and will fail exceptionally
 if it isn't.
 
+<!-- prettier-ignore -->
+!!! example annotate "Example sender type usage"
+    Assume that `SubSender` extends `Sender`.
+
+    ```java
+    Command.Builder<Sender> builder = manager.commandBuilder("command");
+    Command.Builder<SubSender> subBuilder = builder.senderType(SubSender.class);
+    ```
+
 #### Command meta
 
 Command meta-data is used to attach key-value pairs to the commands, which may then be used by different components

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -37,6 +37,7 @@ nav:
       - cloud-spring: https://github.com/incendo/cloud-spring
   - Other:
       - cloud-irc: other/irc.md
+      - cloud-requirements: https://github.com/incendo/cloud-requirements
 theme:
   name: material
   features: