doc: updated docs for throw() to pass status as first param. (#1268)

Author: WaleedAshraf

docs/api/context.md

@@ -118,7 +118,7 @@ throw err;
 ctx.throw(401, 'access_denied', { user: user });
 ```
 
-Koa uses [http-errors](https://github.com/jshttp/http-errors) to create errors.
+Koa uses [http-errors](https://github.com/jshttp/http-errors) to create errors. `status` should only be passed as the first parameter.
 
 ### ctx.assert(value, [status], [msg], [properties])
 

lib/context.js

@@ -73,19 +73,20 @@ const proto = module.exports = {
   assert: httpAssert,
 
   /**
-   * Throw an error with `msg` and optional `status`
-   * defaulting to 500. Note that these are user-level
+   * Throw an error with `status` (default 500) and
+   * `msg`. Note that these are user-level
    * errors, and the message may be exposed to the client.
    *
    *    this.throw(403)
-   *    this.throw('name required', 400)
    *    this.throw(400, 'name required')
    *    this.throw('something exploded')
-   *    this.throw(new Error('invalid'), 400);
-   *    this.throw(400, new Error('invalid'));
+   *    this.throw(new Error('invalid'))
+   *    this.throw(400, new Error('invalid'))
    *
    * See: https://github.com/jshttp/http-errors
    *
+   * Note: `stats` should only be passed as the first parameter.
+   *
    * @param {String|Number|Error} err, msg or status
    * @param {String|Number|Error} [err, msg or status]
    * @param {Object} [props]