chore: fix jsdocs (#3627)

eggjs · Apr 12, 2019 · 4b13a1f · 4b13a1f
1 parent 0fa9bdb
commit 4b13a1f
Show file tree

Hide file tree

Showing 8 changed files with 37 additions and 13 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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