From 65c130db5bdb9d971bb695966c9a22efd3b56d52 Mon Sep 17 00:00:00 2001
From: jongleberry <jonathanong@users.noreply.github.com>
Date: Tue, 7 Mar 2017 23:04:43 -0800
Subject: [PATCH] readme docs++ (#932)

* Better expose documentation in overview readme

* Add code examples for context, request and response

* docs++

* fix indentation
---
 Readme.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 72 insertions(+), 5 deletions(-)

diff --git a/Readme.md b/Readme.md
index 5d2c2df..fb47dad 100644
--- a/Readme.md
+++ b/Readme.md
@@ -87,6 +87,78 @@ The middleware signature changed between v1.x and v2.x.  The older signature is
 Please see the [Migration Guide](docs/migration.md) for more information on upgrading from v1.x and
 using v1.x middleware with v2.x.
 
+## Context, Request and Response
+
+Each middleware receives a Koa `Context` object that encapsulates an incoming
+http message and the corresponding response to that message.  `ctx` is often used
+as the parameter name for the context object.
+
+```js
+app.use(async (ctx, next) => { await next(); });
+```
+
+Koa provides a `Request` object as the `request` property of the `Context`.  
+Koa's `Request` object provides helpful methods for working with
+http requests which delegate to an [IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage)
+from the node `http` module.
+
+Here is an example of checking that a requesting client supports xml.
+
+```js
+app.use(async (ctx, next) => {
+  ctx.assert(ctx.request.accepts('xml'), 406);
+  // equivalent to:
+  // if (!ctx.request.accepts('xml')) ctx.throw(406);
+  await next();
+});
+```
+
+Koa provides a `Response` object as the `response` property of the `Context`.  
+Koa's `Response` object provides helpful methods for working with
+http responses which delegate to a [ServerResponse](https://nodejs.org/api/http.html#http_class_http_serverresponse)
+.  
+
+Koa's pattern of delegating to Node's request and response objects rather than extending them
+provides a cleaner interface and reduces conflicts between different middleware and with Node
+itself as well as providing better support for stream handling.  The `IncomingMessage` can still be
+directly accessed as the `req` property on the `Context` and `ServerResponse` can be directly
+accessed as the `res` property on the `Context`.
+
+Here is an example using Koa's `Response` object to stream a file as the response body.
+
+```js
+app.use(async (ctx, next) => {
+  await next();
+  ctx.response.type = 'xml';
+  ctx.response.body = fs.createReadStream('really_large.xml');
+});
+```
+
+The `Context` object also provides shortcuts for methods on its `request` and `response`.  In the prior
+examples,  `ctx.type` can be used instead of `ctx.request.type` and `ctx.accepts` can be used
+instead of `ctx.request.accepts`.
+
+For more information on `Request`, `Response` and `Context`, see the [Request API Reference](docs/api/request.md),
+[Response API Reference](docs/api/response.md) and [Context API Reference](docs/api/context.md).
+
+## Koa Application
+
+The object created when executing `new Koa()` is known as the Koa application object.
+
+The application object is Koa's interface with node's http server and handles the registration
+of middleware, dispatching to the middleware from http, default error handling, as well as
+configuration of the context, request and response objects.
+
+Learn more about the application object in the [Application API Reference](docs/api/index.md).
+
+## Documentation
+
+ - [Usage Guide](docs/guide.md)
+ - [Error Handling](docs/error-handling.md)
+ - [Koa for Express Users](docs/koa-vs-express.md)
+ - [FAQ](docs/faq.md)
+ - [API documentation](docs/api/index.md)
+
 ## Babel setup
 
 If you're not using `node v7.6+`, we recommend setting up `babel` with [`babel-preset-env`](https://github.com/babel/babel-preset-env):
@@ -132,7 +204,6 @@ See [AUTHORS](AUTHORS).
 
 ## Community
 
- - [API](docs/api/index.md) documentation
  - [Badgeboard](https://koajs.github.io/badgeboard) and list of official modules
  - [Examples](https://github.com/koajs/examples)
  - [Middleware](https://github.com/koajs/koa/wiki) list
@@ -140,13 +211,9 @@ See [AUTHORS](AUTHORS).
  - [G+ Community](https://plus.google.com/communities/101845768320796750641)
  - [Reddit Community](https://www.reddit.com/r/koajs)
  - [Mailing list](https://groups.google.com/forum/#!forum/koajs)
- - [Guide](docs/guide.md)
- - [FAQ](docs/faq.md)
  - [中文文档](https://github.com/guo-yu/koa-guide)
  - __[#koajs]__ on freenode
 
-
-
 ## Backers
 
 Support us with a monthly donation and help us continue our activities.