docs: add res.lastModified and res.etag among other things

docs/api/context.md

@@ -93,6 +93,8 @@
 
  - `signed` the cookie requested should be signed
 
+  Note: koa uses the [cookies](https://github.com/jed/cookies) module where options are simply passed.
+
 ### ctx.cookies.set(name, value, [options])
 
   Set cookie `name` to `value` with `options`:
@@ -104,19 +106,21 @@
  - `secure` secure cookie
  - `httpOnly` server-accessible cookie, __true__ by default
 
-### ctx.error(msg, [status])
+  Note: koa uses the [cookies](https://github.com/jed/cookies) module where options are simply passed.
+
+### ctx.throw(msg, [status])
 
   Helper method to throw an error with a `.status` property
   that will allow Koa to respond appropriately. The following
   combinations are allowed:
 
 ```js
-this.error(403)
+this.throw(403)
-this.error('name required', 400)
+this.throw('name required', 400)
-this.error('something exploded')
+this.throw('something exploded')
 ```
 
-  For example `this.error('name required', 400)` is requivalent to:
+  For example `this.throw('name required', 400)` is requivalent to:
 
 ```js
 var err = new Error('name required');
@@ -129,4 +133,3 @@ throw err;
   client responses, which is typically not the case for
   error messages since you do not want to leak failure
   details.
-  

docs/api/index.md

@@ -53,6 +53,8 @@ http.createServer(app.callback()).listen(3001);
 
   Return a callback function suitable for the `http.createServer()`
   method to handle a request.
+  You may also use this callback function to mount your koa app in a
+  Connect/Express app.
 
 ### app.use(function)
 
@@ -101,8 +103,8 @@ app.on('error', function(err){
   If an error in the req/res cycle and it is _not_ possible to respond to the client, the `Context` instance is also passed:
 
 ```js
-app.on('error', function(err){
+app.on('error', function(err, ctx){
-  log.error('server error', err);
+  log.error('server error', err, ctx);
 });
 ```
 
@@ -120,6 +122,11 @@ app.on('error', function(err){
   client, you may wish to `stat()` and set the `Content-*` header fields
   appropriately to bypass the read.
 
+  On a valid __HEAD__ request, you should either set the status code
+  to anything but `200` or set `this.body = ''`,
+  otherwise koa will not consider the request "handled" and instead
+  respond with a 404.
+
 ### Socket Errors
 
   Node http servers emit a "clientError" event when a socket error occurs. You'll probably want to delegate this to your

docs/api/request.md

@@ -22,7 +22,7 @@
 
 ### req.length
 
-  Return request Content-Length as a number when present, or undefined.
+  Return request Content-Length as a number when present, or `undefined`.
 
 ### req.type
 
@@ -81,6 +81,14 @@ this.query = { next: '/login' };
 
   Set raw query string.
 
+### req.search
+
+  Get raw query string with the `?`.
+
+### req.search=
+
+  Set raw query string.
+
 ### req.host
 
   Get host void of port number when present. Supports `X-Forwarded-Host`
@@ -282,28 +290,3 @@ this.acceptsLanguages();
 // => ["es", "pt", "en"]
 ```
 
-### req.error(msg, [status])
-
-  Helper method to throw an error with a `.status` property
-  that will allow Koa to respond appropriately. The following
-  combinations are allowed:
-
-```js
-this.error(403)
-this.error('name required', 400)
-this.error('something exploded')
-```
-
-  For example `this.error('name required', 400)` is requivalent to:
-
-```js
-var err = new Error('name required');
-err.status = 400;
-throw err;
-```
-
-  Note that these are user-level errors and are flagged with
-  `err.expose` meaning the messages are appropriate for 
-  client responses, which is typically not the case for
-  error messages since you do not want to leak failure
-  details.

docs/api/response.md

@@ -87,7 +87,7 @@
 ### res.length
 
   Return response Content-Length as a number when present, or deduce
-  from `res.body` when possible, or undefined.
+  from `res.body` when possible, or `undefined`.
 
 ### res.body
 
@@ -186,7 +186,7 @@ this.type = 'png';
 
 ### res.redirect(url, [alt])
 
-  Perform a 302 redirect to `url`.
+  Perform a [302] redirect to `url`.
 
   The string "back" is special-cased
   to provide Referrer support, when Referrer
@@ -200,11 +200,11 @@ this.redirect('http://google.com');
 ```
 
   To alter the default status of `302` or the response
-  body simply re-assign after this call:
+  body simply assign before and re-assign after this call:
 
 ```js
-this.redirect('/cart');
 this.status = 301;
+this.redirect('/cart');
 this.body = 'Redirecting to shopping cart';
 ```
 
@@ -219,3 +219,24 @@ this.body = 'Redirecting to shopping cart';
   Check if a response header has already been sent. Useful for seeing
   if the client may be notified on error.
 
+### res.lastModified
+
+  Return the `Last-Modified` header as a `Date`, if it exists.
+
+### res.lastModified=
+
+  Set the `Last-Modified` header as an appropriate UTC string.
+  You can either set it as a `Date` or date string.
+
+```js
+this.response.lastModified = new Date();
+```
+
+### res.etag=
+
+  Set the ETag of a response including the wrapped `"`s.
+  Note that there is no corresponding `res.etag` getter.
+
+```js
+this.response.etag = crypto.createHash('md5').update(this.body).digest('hex');
+```