Document iterators, fixes #91, fixes #99

docs/iterators/README.md

@@ -0,0 +1,60 @@
+# Iterators
+
+Iterators are the next level after promises. While promises resolve once and with one value, iterators allow a set of items to be consumed.
+
+## Iterator Consumption
+
+Every iterator in Amp follows the `Amp\Iterator` interface.
+
+```php
+namespace Amp;
+
+interface Iterator {
+    public function advance(): Promise;
+    public function getCurrent();
+}
+```
+
+`advance()` returns a `Promise` and its resolution value tells whether there's an element to consume or not. If it resolve to `true`, `getCurrent()` can be used to consume the element at the current position, otherwise the iterator ended. In case an exception happens, `advance()` returns a failed promise and `getCurrent()` throws the failure reason on call.
+
+### Simple Consumption Example
+
+```php
+$iterator = foobar();
+
+while (yield $iterator->advance()) {
+    $element = $iterator->getCurrent();
+    // do something with $element
+}
+```
+
+## Iterator Creation
+
+### Emitter
+
+What `Deferred` is for promises, is `Emitter` for iterators. A library that returns an `Iterator` for asynchronous consumption of an iterable result creates an `Amp\Emitter` and returns the `Iterator` using `iterate()`. This ensures a consumer can only consume the iterator, but not emit values or complete the iterator.
+
+#### `emit()`
+
+`emit()` emits a new value to the `Iterator`, which can be consumed by a consumer. The emitted value is passed as first argument to `emit()`. `emit()` returns a `Promise` that can be waited on before emitting new values. This allow emitting values just as fast as the consumer can consume them.
+
+#### `complete()`
+
+`complete()` marks the `Emitter` / linked `Iterator` as complete. No further emits are allowed after completing an `Emitter` / `Iterator`. 
+
+### Producer
+
+`Producer` is a simplified form of `Emitter` that can be used when a single coroutine can emit all values.
+
+`Producer` accepts a `callable` as first constructor parameter that gets run as a coroutine and passed a `$emit` callable that can be used to emit values just like the `emit()` method in `Emitter`.
+
+#### Example
+
+```php
+$iterator = new Producer(function (callable $emit) {
+    yield $emit(1);
+    yield $emit(new Delayed(500, 2));
+    yield $emit(3);
+    yield $emit(4);
+});
+```

docs/iterators/transformation.md

@@ -1,3 +1,3 @@
-# Promise Transformation
+# Iterator Transformation
 
 This is a documentation stub. Please help writing this documentation. See [#105](https://github.com/amphp/amp/issues/105).

docs/streams/README.md

@@ -1,3 +0,0 @@
-# Streams
-
-This is a documentation stub. Please help writing this documentation. See [#91](https://github.com/amphp/amp/issues/91) and [#99](https://github.com/amphp/amp/issues/99).