From 4b13a1ffbed0895731bf38f72d5786d4b15f263f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?TZ=20=7C=20=E5=A4=A9=E7=8C=AA?= Date: Fri, 12 Apr 2019 22:39:32 +0800 Subject: [PATCH] chore: fix jsdocs (#3627) --- app/extend/context.js | 2 +- app/extend/helper.js | 4 ++-- app/extend/request.js | 18 ++++++++++++++---- app/extend/response.js | 12 +++++++++++- lib/agent.js | 2 +- lib/application.js | 2 +- lib/core/base_context_logger.js | 6 +++++- lib/egg.js | 4 ++-- 8 files changed, 37 insertions(+), 13 deletions(-) diff --git a/app/extend/context.js b/app/extend/context.js index ed8041e471..87b0b7d9e9 100644 --- a/app/extend/context.js +++ b/app/extend/context.js @@ -39,7 +39,7 @@ const proto = module.exports = { /** * Shortcut for httpclient.curl * - * @method Context#curl + * @function Context#curl * @param {String|Object} url - request url address. * @param {Object} [options] - options for request. * @return {Object} see {@link ContextHttpClient#curl} diff --git a/app/extend/helper.js b/app/extend/helper.js index 90e0d8064c..3120944d25 100644 --- a/app/extend/helper.js +++ b/app/extend/helper.js @@ -7,7 +7,7 @@ module.exports = { /** * Generate URL path(without host) for route. Takes the route name and a map of named params. - * @method Helper#pathFor + * @function Helper#pathFor * @param {String} name - Router Name * @param {Object} params - Other params * @@ -25,7 +25,7 @@ module.exports = { /** * Generate full URL(with host) for route. Takes the route name and a map of named params. - * @method Helper#urlFor + * @function Helper#urlFor * @param {String} name - Router name * @param {Object} params - Other params * @example diff --git a/app/extend/request.js b/app/extend/request.js index 310d7bb76b..109810f536 100644 --- a/app/extend/request.js +++ b/app/extend/request.js @@ -101,9 +101,9 @@ module.exports = { }, /** - * Get or set the request remote IPv4 address + * Get the request remote IPv4 address * @member {String} Request#ip - * @param {String} ip - IPv4 address + * @return {String} IPv4 address * @example * ```js * this.request.ip @@ -122,6 +122,17 @@ module.exports = { return this._ip; }, + /** + * Set the request remote IPv4 address + * @member {String} Request#ip + * @param {String} ip - IPv4 address + * @example + * ```js + * this.request.ip + * => '127.0.0.1' + * => '111.10.2.1' + * ``` + */ set ip(ip) { this._ip = ip; }, @@ -232,10 +243,9 @@ module.exports = { /** * Set query-string as an object. * - * @method Request#query + * @function Request#query * @param {Object} obj set querystring and query object for request. * @return {void} - * @api public */ set query(obj) { this.querystring = querystring.stringify(obj); diff --git a/app/extend/response.js b/app/extend/response.js index 4695a46697..643d53f610 100644 --- a/app/extend/response.js +++ b/app/extend/response.js @@ -76,7 +76,7 @@ module.exports = { * And access log should save 500 not 302, * then the `realStatus` can help us find out the real status code. * @member {Number} Response#realStatus - * @param {Number} status The status code to be set. + * @return {Number} The status code to be set. */ get realStatus() { if (this[REAL_STATUS]) { @@ -85,6 +85,16 @@ module.exports = { return this.status; }, + /** + * Set a real status code. + * + * e.g.: Using 302 status redirect to the global error page + * instead of show current 500 status page. + * And access log should save 500 not 302, + * then the `realStatus` can help us find out the real status code. + * @member {Number} Response#realStatus + * @param {Number} status The status code to be set. + */ set realStatus(status) { this[REAL_STATUS] = status; }, diff --git a/lib/agent.js b/lib/agent.js index 6259523f14..5dbbb8d106 100644 --- a/lib/agent.js +++ b/lib/agent.js @@ -14,7 +14,7 @@ const EGG_PATH = Symbol.for('egg#eggPath'); */ class Agent extends EggApplication { /** - * @constructor + * @class * @param {Object} options - see {@link EggApplication} */ constructor(options = {}) { diff --git a/lib/application.js b/lib/application.js index 4f34c42261..75cff1f420 100644 --- a/lib/application.js +++ b/lib/application.js @@ -52,7 +52,7 @@ function escapeHeaderValue(value) { class Application extends EggApplication { /** - * @constructor + * @class * @param {Object} options - see {@link EggApplication} */ constructor(options = {}) { diff --git a/lib/core/base_context_logger.js b/lib/core/base_context_logger.js index f4a8a3b551..64baff541d 100644 --- a/lib/core/base_context_logger.js +++ b/lib/core/base_context_logger.js @@ -5,7 +5,7 @@ const CALL = Symbol('BaseContextLogger#call'); class BaseContextLogger { /** - * @constructor + * @class * @param {Context} ctx - context instance * @param {String} pathName - class path name * @since 1.0.0 @@ -29,6 +29,7 @@ class BaseContextLogger { /** * @member {Function} BaseContextLogger#debug + * @param {...any} args - log msg * @since 1.2.0 */ debug(...args) { @@ -37,6 +38,7 @@ class BaseContextLogger { /** * @member {Function} BaseContextLogger#info + * @param {...any} args - log msg * @since 1.2.0 */ info(...args) { @@ -45,6 +47,7 @@ class BaseContextLogger { /** * @member {Function} BaseContextLogger#warn + * @param {...any} args - log msg * @since 1.2.0 */ warn(...args) { @@ -53,6 +56,7 @@ class BaseContextLogger { /** * @member {Function} BaseContextLogger#error + * @param {...any} args - log msg * @since 1.2.0 */ error(...args) { diff --git a/lib/egg.js b/lib/egg.js index 96c978b534..b4421e4654 100644 --- a/lib/egg.js +++ b/lib/egg.js @@ -33,7 +33,7 @@ const CLUSTER_CLIENTS = Symbol.for('egg#clusterClients'); class EggApplication extends EggCore { /** - * @constructor + * @class * @param {Object} options * - {Object} [type] - type of instance, Agent and Application both extend koa, type can determine what it is. * - {String} [baseDir] - app root dir, default is `process.cwd()` @@ -508,7 +508,7 @@ class EggApplication extends EggCore { /** * Create egg context - * @method EggApplication#createContext + * @function EggApplication#createContext * @param {Req} req - node native Request object * @param {Res} res - node native Response object * @return {Context} context object