From 3f3a4f8d111ca28459657ae40121c78057f4fcc8 Mon Sep 17 00:00:00 2001
From: Aaron Piotrowski <aaron@trowski.com>
Date: Sat, 25 Jan 2025 12:42:38 -0600
Subject: [PATCH] Add more Future docs

---
 README.md | 43 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 41 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 52f5c856..abbbc0dc 100644
--- a/README.md
+++ b/README.md
@@ -137,9 +137,14 @@ print '++ Script end' . PHP_EOL;
 
 ### Future
 
-A `Future` is an object representing the eventual result of an asynchronous operation. There are three states:
+A `Future` is an object representing the eventual result of an asynchronous operation. Such placeholders are also
+called "promises" in other frameworks or languages such as JavaScript. We chose to not use the "promises" name as a
+`Future` does not have a `then` method, which is typical of most promise implementations. Futures are primarily designed
+to be awaited in coroutines, though `Future` also has methods which act upon the result, returning another future.
 
-- **Completed successfully**: The future has been completed successfully.
+A future may be in one of three states:
+
+- **Completed**: The future has been completed successfully.
 - **Errored**: The future failed with an exception.
 - **Pending**: The future is still pending.
 
@@ -176,6 +181,40 @@ try {
 }
 ```
 
+```php
+public function await(): mixed
+```
+
+Suspends the current coroutine until the future is completed or errors. The future result is returned or an exception
+thrown if the future errored.
+
+```php
+/** @param Closure(mixed $value): mixed $map */
+public function map(Closure $map): Future
+```
+
+Attaches a callback which is invoked if the future completes successfully, passing the future result as an argument.
+Another future is returned, which either completes with the return value of the callback, or errors if the callback
+throws an exception.
+
+```php
+/** @param Closure(Throwable $exception): mixed $catch */
+public function catch(Closure $catch): Future
+```
+
+Attaches a callback which is invoked if the future errors, passing the exception as the callback parameter.
+Another future is returned, which either completes with the return value of the callback, or errors if the callback
+throws an exception.
+
+```php
+/** @param Closure(): void $finally */
+public function finally(Closure $finally): Future
+```
+
+Attaches a callback which is always invoked, whether the future completes or errors.
+Another future is returned, which either completes with same value as the future, or errors if the callback
+throws an exception.
+
 #### Combinators
 
 In concurrent applications, there will be multiple futures, where you might want to await them all or just the first one.