From e450bbe70a1c1ee825821ce5fd930f67d6f823fc Mon Sep 17 00:00:00 2001
From: Niklas Keller <me@kelunik.com>
Date: Wed, 3 May 2017 15:12:15 +0200
Subject: [PATCH] Document coroutine helpers, fixes #100

---
 docs/coroutines/helpers.md | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)
 create mode 100644 docs/coroutines/helpers.md

diff --git a/docs/coroutines/helpers.md b/docs/coroutines/helpers.md
new file mode 100644
index 0000000..1139886
--- /dev/null
+++ b/docs/coroutines/helpers.md
@@ -0,0 +1,35 @@
+# Coroutine Helpers
+
+`Amp\Coroutine` requires a already instantiated `Generator` to be passed to its constructor. Always calling a callable before passing the `Generator` to `Amp\Coroutine` is unnecessary boilerplate.
+
+## `coroutine()`
+
+Returns a new function that wraps `$callback` in a promise/coroutine-aware function that automatically runs generators as coroutines. The returned function always returns a promise when invoked. Errors have to be handled by the callback caller or they will go unnoticed.
+
+```php
+function coroutine(callable $callback): callable { ... }
+```
+
+Use this function to create a coroutine-aware callable for a promise-aware callback caller.
+
+## `asyncCoroutine()`
+
+Same as `coroutine()` but doesn't return a `Promise` when the returned callback is called. Instead, promises are passed to `Amp\Promise\rethrow()` to handle errors automatically.
+
+## `call()`
+
+```php
+function call(callable $callback, ...$args): Promise { ... }
+```
+
+Calls the given function, always returning a promise. If the function returns a `Generator`, it will be run as a coroutine. If the function throws, a failed promise will be returned.
+
+`call($callable, ...$args)` is equivalent to `coroutine($callable)(...$args)`.
+
+## `asyncCall()`
+
+```php
+function asyncCall(callable $callback, ...$args) { ... }
+```
+
+Same as `call()`, but doesn't return the `Promise`. Promises are automatically passed to `Amp\Promise\rethrow` for error handling.