From a62d6da15188406b59d2772c7c824f4740f18ab9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Alexander=20S=C3=B6derberg?=
 <alexander.soderberg@incendo.org>
Date: Fri, 2 Feb 2024 12:07:50 +0100
Subject: [PATCH] feat: documented future-returning handlers

---
 docs/annotations/index.md | 10 ++++++++++
 docs/core/index.md        |  7 ++++++-
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/docs/annotations/index.md b/docs/annotations/index.md
index f38ed3a..fffef62 100644
--- a/docs/annotations/index.md
+++ b/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:
diff --git a/docs/core/index.md b/docs/core/index.md
index a288af3..e733ca9 100644
--- a/docs/core/index.md
+++ b/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)>).