From bfa012e8105857a1b9c22894d74ef98b0dfff7af Mon Sep 17 00:00:00 2001
From: Aaron Piotrowski <aaron@trowski.com>
Date: Tue, 13 Mar 2018 10:26:29 -0500
Subject: [PATCH] Add Payload docs

---
 docs/message.md |  4 ++++
 docs/payload.md | 24 ++++++++++++++++++++++++
 2 files changed, 28 insertions(+)
 create mode 100644 docs/payload.md

diff --git a/docs/message.md b/docs/message.md
index 7060534..59bc420 100644
--- a/docs/message.md
+++ b/docs/message.md
@@ -2,6 +2,10 @@
 title: Message
 permalink: /message
 ---
+
+{:.note}
+> `Message` has been deprecated. Use [`Payload`](./payload.md) instead.
+
 `Message` implements both `InputStream` _and_ `Promise`. This allows consuming a message either in chunks (streaming) or consume everything at once (buffering).
 
 ## Buffering
diff --git a/docs/payload.md b/docs/payload.md
new file mode 100644
index 0000000..9c260e4
--- /dev/null
+++ b/docs/payload.md
@@ -0,0 +1,24 @@
+---
+title: Payload
+permalink: /payload
+---
+`Payload` implements `InputStream` while also providing a method `buffer()` for buffering the entire contents. This allows consuming a message either in chunks (streaming) or consume everything at once (buffering). When the object is destructed, any remaining data in the stream is automatically consumed and discarded. This class is useful for small payloads or when the entire contents of a stream is needed before any processing can be done.
+
+## Buffering
+
+Buffering a complete input stream is quite easy, you can simply `yield` the promise returned from `buffer()` just like any other `Promise`. If you have an `InputStream` that's not a `Payload`, simply create a new instance from it using `new Payload($inputStream)`.
+
+```php
+$payload = new Payload($inputStream);
+$content = yield $payload->buffer();
+```
+
+## Streaming
+
+Sometimes it's useful / possible to consume a payload in chunks rather than first buffering it completely. An example might be streaming a large HTTP response body directly to disk.
+
+```php
+while (($chunk = yield $payload->read()) !== null) {
+    // Use $chunk here, works just like any other InputStream
+}
+```