feat: documented future-returning handlers

docs/annotations/index.md

@@ -111,6 +111,16 @@ or custom injections.
 
 The annotation may be repeated in order to generate multiple commands from the same method.
 
+The command method may return [`CompletableFuture<Void>`](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/CompletableFuture.html)
+in which case the execution coordinator will wait for the returned future to complete:
+
+```java
+@Command("command")
+public CompletableFuture<Void> command() {
+  return CompletableFuture.supplyAsync(() -> null);
+}
+```
+
 ### Syntax
 
 There are three different parts that make up the command syntax:

docs/core/index.md

@@ -383,7 +383,12 @@ builder.handler(ctx -> {
 You may implement
 [`CommandExecutionHandler.FutureCommandExecutionHandler`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/execution/CommandExecutionHandler.FutureCommandExecutionHandler.html)
 to have the handler be a future-returning
-function. Cloud will wait for the future to complete and will handle any completion exceptions gracefully.
+function. Cloud will wait for the future to complete and will handle any completion exceptions gracefully. You may
+use the `futureHandler` command builder method to specify a future-returning handler:
+
+```java
+builder.futureHandler(ctx -> CompletableFuture.completedFuture(null))
+```
 
 You may delegate to other handlers using
 [`CommandExecutionHandler.delegatingExecutionHandler`](<https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/execution/CommandExecutionHandler.html#delegatingExecutionHandler(java.util.List)>).