From e96ddb6a884ef767c8653242c666dcc7381222b7 Mon Sep 17 00:00:00 2001
From: DongWei <maledong_forwork@foxmail.com>
Date: Wed, 9 May 2018 23:52:28 +0800
Subject: [PATCH] docs: Modifications of comments and full translations
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Change Logs:

1）/egg/README.zh-CN.md：Line 66 to 68 (Translate English part to
Chinese in README.zh-CN.md）.

2）/egg/app/extend/request.js：Line 181 (Correct English syntaxes
error).

3）Comments added for:app/extend/context.js

4）Comments merged for:
4.1）app/extend/request.js
4.2）app/extend/response.js

Why to merge comments for properties?

It's that properties get/set is reguarded as a "whole property", this
means you ONLY need to write one snippet of comments on either "get" or "set"
(usually on the 1st part).

If you write two snippets of comments on both get and set, if you move
your mouse onto the property, you'll find either get or set will have a wrong intellisense tip of comments.
---
 README.zh-CN.md        |  4 ++--
 app/extend/context.js  |  4 ++++
 app/extend/request.js  |  9 +++------
 app/extend/response.js | 36 ++++++++++++++++++++++++++----------
 4 files changed, 35 insertions(+), 18 deletions(-)

diff --git a/README.zh-CN.md b/README.zh-CN.md
index 752c663be4..2691f38abc 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -63,9 +63,9 @@ $ open http://localhost:7001
 
 ## 贡献代码
 
-Please let us know what we can help, check [issues](https://github.com/eggjs/egg/issues) for bug reporting and suggestion.
+请告知我们可以为你做些什么，不过在此之前，请检查一下是否有[已经存在的Bug或者意见](https://github.com/eggjs/egg/issues)。
 
-If you are a contributor, follow [CONTRIBUTING](CONTRIBUTING.md).
+如果你是一个代码贡献者，请参考[代码贡献规范](CONTRIBUTING.md)。
 
 ## 开源协议
 
diff --git a/app/extend/context.js b/app/extend/context.js
index 313e808905..1bd8ccc912 100644
--- a/app/extend/context.js
+++ b/app/extend/context.js
@@ -13,6 +13,10 @@ const CONTEXT_HTTPCLIENT = Symbol('Context#httpclient');
 
 
 const proto = module.exports = {
+
+  /**
+   * Get the current visitor's cookies.
+   */
   get cookies() {
     if (!this[COOKIES]) {
       this[COOKIES] = new this.app.ContextCookies(this, this.app.keys);
diff --git a/app/extend/request.js b/app/extend/request.js
index eb2dc7ef7b..92a4b5338d 100644
--- a/app/extend/request.js
+++ b/app/extend/request.js
@@ -95,8 +95,9 @@ module.exports = {
   },
 
   /**
-   * Request remote IPv4 address
+   * Get or set the request remote IPv4 address
    * @member {String} Request#ip
+   * @param {String} ip - IPv4 address
    * @example
    * ```js
    * this.request.ip
@@ -115,10 +116,6 @@ module.exports = {
     return this._ip;
   },
 
-  /**
-   * Set the remote address
-   * @param {String} ip - IPv4 address
-   */
   set ip(ip) {
     this._ip = ip;
   },
@@ -178,7 +175,7 @@ module.exports = {
   },
 
   /**
-   * get params pass by querystring, all value are String type.
+   * get params pass by querystring, all values are of string type.
    * @member {Object} Request#query
    * @example
    * ```js
diff --git a/app/extend/response.js b/app/extend/response.js
index 60e06e743f..6c9d110927 100644
--- a/app/extend/response.js
+++ b/app/extend/response.js
@@ -5,10 +5,20 @@ const isJSON = require('koa-is-json');
 const REAL_STATUS = Symbol('Context#realStatus');
 
 module.exports = {
-  set length(n) {
+
+  /**
+   * Get or set the length of content.
+   *
+   * For Get: If the original content length is null or undefined, it will read out
+   * the body's content length as the return value.
+   *
+   * @member {Number} Response#type
+   * @param {Number} len The content-length to be set.
+   */
+  set length(len) {
     // copy from koa
     // change header name to lower case
-    this.set('content-length', n);
+    this.set('content-length', len);
   },
 
   get length() {
@@ -27,6 +37,17 @@ module.exports = {
     return parseInt(len, 10);
   },
 
+  /**
+   * Get or set the content-type.
+   *
+   * For Set: If type is null or undefined, this property will be removed.
+   *
+   * For Get: If the value is null or undefined, an empty string will be returned;
+   * if you have multiple values seperated by `;`, ONLY the first one will be returned.
+   *
+   * @member {String} Response#type
+   * @param {String} type The content-type to be set.
+   */
   set type(type) {
     // copy from koa
     // change header name to lower case
@@ -46,13 +67,14 @@ module.exports = {
   },
 
   /**
-   * read response real status code.
+   * Get or 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} Context#realStatus
+   * @member {Number} Response#realStatus
+   * @param {Number} status The status code to be set.
    */
   get realStatus() {
     if (this[REAL_STATUS]) {
@@ -61,12 +83,6 @@ module.exports = {
     return this.status;
   },
 
-  /**
-   * set response real status code.
-   *
-   * @member {Void} Response#realStatus
-   * @param {Number} status the real status code
-   */
   set realStatus(status) {
     this[REAL_STATUS] = status;
   },