docs: Provide more typings for application's context and request/resp…

…onse (koajs#1726)

A bit more detailed types to help users of the library

lib/application.js

@@ -20,6 +20,20 @@ const http = require('http')
 const only = require('only')
 const { HttpError } = require('http-errors')
 
+/** @typedef {typeof import ('./context') & {
+ *  app: Application
+ *  req: import('http').IncomingMessage
+ *  res: import('http').ServerResponse
+ *  request: KoaRequest
+ *  response: KoaResponse
+ *  state: any
+ *  originalUrl: string
+ * }} Context */
+
+/** @typedef {typeof import('./request')} KoaRequest */
+
+/** @typedef {typeof import('./response')} KoaResponse */
+
 /**
  * Expose `Application` class.
  * Inherits from `Emitter.prototype`.
@@ -77,7 +91,7 @@ module.exports = class Application extends Emitter {
    *    http.createServer(app.callback()).listen(...)
    *
    * @param {Mixed} ...
-   * @return {Server}
+   * @return {import('http').Server}
    * @api public
    */
 
@@ -119,7 +133,7 @@ module.exports = class Application extends Emitter {
    *
    * Old-style middleware will be converted.
    *
-   * @param {Function} fn
+   * @param {(context: Context) => Promise<any | void>} fn
    * @return {Application} self
    * @api public
    */
@@ -181,8 +195,11 @@ module.exports = class Application extends Emitter {
    */
 
   createContext (req, res) {
+    /** @type {Context} */
     const context = Object.create(this.context)
+    /** @type {KoaRequest} */
     const request = context.request = Object.create(this.request)
+    /** @type {KoaResponse} */
     const response = context.response = Object.create(this.response)
     context.app = request.app = response.app = this
     context.req = request.req = response.req = req