升级到 v8.0.0

README.md

@@ -1,4 +1,4 @@
 # node-api-cn
-Node.js API 中文文档 v6.10.3
+Node.js API 中文文档 v8.0.0
 
 http://nodejs.cn/api/

addons/building.md

@@ -1,6 +1,6 @@
 
 当源代码已被编写，它必须被编译成二进制 `addon.node` 文件。
-要做到这点，需在项目的顶层创建一个名为 `binding.gyp` 的文件，它使用一个类似 JSON 的格式来描述你的模块的构建配置。
+要做到这点，需在项目的顶层创建一个名为 `binding.gyp` 的文件，它使用一个类似 JSON 的格式来描述模块的构建配置。
 该文件会被 [node-gyp]（一个用于编译 Node.js 插件的工具）使用。
 
 

addons/n_api.md

@@ -0,0 +1,18 @@
+
+> Stability: 1 - Experimental
+
+N-API is an API for building native Addons. It is independent from
+the underlying JavaScript runtime (ex V8) and is maintained as part of
+Node.js itself. This API will be Application Binary Interface (ABI) stable
+across version of Node.js. It is intended to insulate Addons from
+changes in the underlying JavaScript engine and allow modules
+compiled for one version to run on later versions of Node.js without
+recompilation. Addons are built/packaged with the same approach/tools
+outlined in this document (node-gyp, etc.). The only difference is the
+set of APIs that are used by the native code. Instead of using the V8
+or [Native Abstractions for Node.js][] APIs, the functions available
+in the N-API are used.
+
+The functions available and how to use them are documented in the
+section titled [C/C++ Addons - N-API](n-api.html).
+

addons/void_atexit_callback_args.md

@@ -55,7 +55,7 @@ void init(Local<Object> exports) {
   AtExit(at_exit_cb1, exports->GetIsolate());
 }
 
-NODE_MODULE(addon, init);
+NODE_MODULE(addon, init)
 
 }  // namespace demo
 ```

assert/assert_deepequal_actual_expected_message.md

@@ -1,15 +1,28 @@
 <!-- YAML
 added: v0.1.21
+changes:
+  - version: v8.0.0
+    pr-url: https://github.com/nodejs/node/pull/12142
+    description: Set and Map content is also compared
+  - version: v6.4.0, v4.7.1
+    pr-url: https://github.com/nodejs/node/pull/8002
+    description: Typed array slices are handled correctly now.
+  - version: v6.1.0, v4.5.0
+    pr-url: https://github.com/nodejs/node/pull/6432
+    description: Objects with circular references can be used as inputs now.
+  - version: v5.10.1, v4.4.3
+    pr-url: https://github.com/nodejs/node/pull/5910
+    description: Handle non-`Uint8Array` typed arrays correctly.
 -->
 * `actual` {any}
 * `expected` {any}
 * `message` {any}
 
 测试 `actual` 参数与 `expected` 参数是否深度相等。
-原始值使用相等运算符（`==`）比较。
+原始值使用 [相等运算符]（`==`）比较。
 
-只比较可枚举的自身属性。
-`deepEqual()` 不比较对象的原型、连接符、或不可枚举的属性。
+只比较 [可枚举的自身属性]。
+[`assert.deepEqual()`] 不比较对象的 [原型]、连接符、或不可枚举的属性（这些情况可以使用 [`assert.deepStrictEqual()`]）。
 这可能会导致一些意料之外的结果。
 例如，下面的例子不会抛出 `AssertionError`，因为 [Error](errors.html#errors_class_error) 对象的属性是不可枚举的：
 
@@ -18,24 +31,27 @@ added: v0.1.21
 assert.deepEqual(Error('a'), Error('b'));
 ```
 
+An exception is made for [`Map`][] and [`Set`][]. Maps and Sets have their
+contained items compared too, as expected.
+
 深度相等意味着子对象的可枚举的自身属性也会被比较：
 
 ```js
 const assert = require('assert');
 
 const obj1 = {
-  a : {
-    b : 1
+  a: {
+    b: 1
   }
 };
 const obj2 = {
-  a : {
-    b : 2
+  a: {
+    b: 2
   }
 };
 const obj3 = {
-  a : {
-    b : 1
+  a: {
+    b: 1
   }
 };
 const obj4 = Object.create(obj1);

assert/assert_deepstrictequal_actual_expected_message.md

@@ -1,23 +1,58 @@
 <!-- YAML
 added: v1.2.0
+changes:
+  - version: v8.0.0
+    pr-url: https://github.com/nodejs/node/pull/12142
+    description: Set and Map content is also compared
+  - version: v6.4.0, v4.7.1
+    pr-url: https://github.com/nodejs/node/pull/8002
+    description: Typed array slices are handled correctly now.
+  - version: v6.1.0
+    pr-url: https://github.com/nodejs/node/pull/6432
+    description: Objects with circular references can be used as inputs now.
+  - version: v5.10.1, v4.4.3
+    pr-url: https://github.com/nodejs/node/pull/5910
+    description: Handle non-`Uint8Array` typed arrays correctly.
 -->
 * `actual` {any}
 * `expected` {any}
 * `message` {any}
 
-大多数情况下与 `assert.deepEqual()` 一样，但有两个例外。
-首先，原始值使用全等运算符（`===`）比较。
-其次，对象的比较包括检查它们的原型是否全等。
+大多数情况下与 `assert.deepEqual()` 一样，但有三个例外：
+
+1. 原始值使用 [全等运算符]（`===`）比较。
+   Set values and Map keys are compared using the [SameValueZero][] comparison. (Which means they are free of the [caveats][]).
+2. 对象的 [原型] 也使用 [全等运算符] 比较。
+3. [Type tags][Object.prototype.toString()] of objects should be the same.
 
 ```js
 const assert = require('assert');
 
-assert.deepEqual({a:1}, {a:'1'});
+assert.deepEqual({a: 1}, {a: '1'});
 // 通过，因为 1 == '1'
 
-assert.deepStrictEqual({a:1}, {a:'1'});
+assert.deepStrictEqual({a: 1}, {a: '1'});
 // 抛出 AssertionError: { a: 1 } deepStrictEqual { a: '1' }
 // 因为 1 !== '1' 使用全等运算符
+
+// The following objects don't have own properties
+const date = new Date();
+const object = {};
+const fakeDate = {};
+
+Object.setPrototypeOf(fakeDate, Date.prototype);
+
+assert.deepEqual(object, fakeDate);
+// OK, doesn't check [[Prototype]]
+assert.deepStrictEqual(object, fakeDate);
+// AssertionError: {} deepStrictEqual Date {}
+// Different [[Prototype]]
+
+assert.deepEqual(date, fakeDate);
+// OK, doesn't check type tags
+assert.deepStrictEqual(date, fakeDate);
+// AssertionError: 2017-03-11T14:25:31.849Z deepStrictEqual Date {}
+// Different type tags
 ```
 
 如果两个值不相等，则抛出一个带有 `message` 属性的 `AssertionError`，其中 `message` 属性的值等于传入的 `message` 参数的值。

assert/assert_doesnotthrow_block_error_message.md

@@ -1,5 +1,12 @@
 <!-- YAML
 added: v0.1.21
+changes:
+  - version: v5.11.0, v4.4.5
+    pr-url: https://github.com/nodejs/node/pull/2407
+    description: The `message` parameter is respected now.
+  - version: v4.2.0
+    pr-url: https://github.com/nodejs/node/pull/3276
+    description: The `error` parameter can now be an arrow function.
 -->
 * `block` {Function}
 * `error` {RegExp|Function}

assert/assert_equal_actual_expected_message.md

@@ -5,7 +5,7 @@ added: v0.1.21
 * `expected` {any}
 * `message` {any}
 
-使用相等运算符（`==`）测试 `actual` 参数与 `expected` 参数是否相等。
+使用 [相等运算符]（`==`）测试 `actual` 参数与 `expected` 参数是否相等。
 
 ```js
 const assert = require('assert');

assert/assert_fail_actual_expected_message_operator.md

@@ -4,7 +4,7 @@ added: v0.1.21
 * `actual` {any}
 * `expected` {any}
 * `message` {any}
-* `operator` {String}
+* `operator` {String} (默认: '!=')
 
 抛出 `AssertionError`。
 如果 `message` 不存在，则错误信息会被设为 `actual` 的值加分隔符 `operator` 再加 `expected` 的值。
@@ -18,5 +18,11 @@ assert.fail(1, 2, undefined, '>');
 
 assert.fail(1, 2, '错误信息', '>');
 // 抛出 AssertionError: 错误信息
+
+assert.fail('错误信息');
+// 抛出 AssertionError: 错误信息
+
+assert.fail('a', 'b');
+// 抛出 AssertionError: 'a' != 'b'
 ```
 

assert/assert_notdeepequal_actual_expected_message.md

@@ -12,18 +12,18 @@ added: v0.1.21
 const assert = require('assert');
 
 const obj1 = {
-  a : {
-    b : 1
+  a: {
+    b: 1
   }
 };
 const obj2 = {
-  a : {
-    b : 2
+  a: {
+    b: 2
   }
 };
 const obj3 = {
-  a : {
-    b : 1
+  a: {
+    b: 1
   }
 };
 const obj4 = Object.create(obj1);

assert/assert_notdeepstrictequal_actual_expected_message.md

@@ -11,10 +11,10 @@ added: v1.2.0
 ```js
 const assert = require('assert');
 
-assert.notDeepEqual({a:1}, {a:'1'});
+assert.notDeepEqual({a: 1}, {a: '1'});
 // 抛出 AssertionError: { a: 1 } notDeepEqual { a: '1' }
 
-assert.notDeepStrictEqual({a:1}, {a:'1'});
+assert.notDeepStrictEqual({a: 1}, {a: '1'});
 // 通过
 ```
 

assert/assert_notequal_actual_expected_message.md

@@ -5,7 +5,7 @@ added: v0.1.21
 * `expected` {any}
 * `message` {any}
 
-使用不等运算符（`!=`）测试是否不相等。
+使用 [不等运算符]（`!=`）测试是否不相等。
 
 ```js
 const assert = require('assert');

assert/assert_notstrictequal_actual_expected_message.md

@@ -5,7 +5,7 @@ added: v0.1.21
 * `expected` {any}
 * `message` {any}
 
-使用不全等运算符（`!==`）测试是否不全等。
+使用 [不全等运算符]（`!==`）测试是否不全等。
 
 ```js
 const assert = require('assert');

assert/assert_strictequal_actual_expected_message.md

@@ -5,7 +5,7 @@ added: v0.1.21
 * `expected` {any}
 * `message` {any}
 
-使用全等运算符（`===`）测试是否全等。
+使用 [全等运算符]（`===`）测试是否全等。
 
 ```js
 const assert = require('assert');

assert/assert_throws_block_error_message.md

@@ -1,5 +1,9 @@
 <!-- YAML
 added: v0.1.21
+changes:
+  - version: v4.2.0
+    pr-url: https://github.com/nodejs/node/pull/3276
+    description: The `error` parameter can now be an arrow function.
 -->
 * `block` {Function}
 * `error` {RegExp|Function}
@@ -41,7 +45,7 @@ assert.throws(
     throw new Error('错误信息');
   },
   function(err) {
-    if ( (err instanceof Error) && /错误/.test(err) ) {
+    if ((err instanceof Error) && /错误/.test(err)) {
       return true;
     }
   },
@@ -53,6 +57,7 @@ assert.throws(
 如果第二个参数是一个字符串，则视为省略 `error` 参数，传入的字符串会被用于 `message`。
 这点比较容易搞错：
 
+<!-- eslint-disable assert-throws-arguments -->
 ```js
 // 这是错误的！不要这么做！
 assert.throws(myFunction, '错误', '没有抛出期望的信息');

assert/caveats.md

@@ -0,0 +1,25 @@
+
+For the following cases, consider using ES2015 [`Object.is()`][],
+which uses the [SameValueZero][] comparison.
+
+```js
+const a = 0;
+const b = -a;
+assert.notStrictEqual(a, b);
+// AssertionError: 0 !== -0
+// Strict Equality Comparison doesn't distinguish between -0 and +0...
+assert(!Object.is(a, b));
+// but Object.is() does!
+
+const str1 = 'foo';
+const str2 = 'foo';
+assert.strictEqual(str1 / 1, str2 / 1);
+// AssertionError: NaN === NaN
+// Strict Equality Comparison can't be used to check NaN...
+assert(Object.is(str1 / 1, str2 / 1));
+// but Object.is() can!
+```
+
+For more information, see
+[MDN's guide on equality comparisons and sameness][mdn-equality-guide].
+

buffer/buf_buffer.md

@@ -0,0 +1,12 @@
+
+The `buffer` property references the underlying `ArrayBuffer` object based on
+which this Buffer object is created.
+
+```js
+const arrayBuffer = new ArrayBuffer(16);
+const buffer = Buffer.from(arrayBuffer);
+
+console.log(buffer.buffer === arrayBuffer);
+// Prints: true
+```
+

buffer/buf_compare_target_targetstart_targetend_sourcestart_sourceend.md

@@ -1,20 +1,27 @@
 <!-- YAML
 added: v0.11.13
+changes:
+  - version: v8.0.0
+    pr-url: https://github.com/nodejs/node/pull/10236
+    description: The `target` parameter can now be a `Uint8Array`.
+  - version: v5.11.0
+    pr-url: https://github.com/nodejs/node/pull/5880
+    description: Additional parameters for specifying offsets are supported now.
 -->
 
-* `target` {Buffer} 要比较的 `Buffer`
-* `targetStart` {Integer} `target` 中开始对比的偏移量。
+* `target` {Buffer|Uint8Array} 要比较的 `Buffer` 或 [`Uint8Array`]。
+* `targetStart` {integer} `target` 中开始对比的偏移量。
   **默认:** `0`
-* `targetEnd` {Integer} `target` 中结束对比的偏移量（不包含）。
+* `targetEnd` {integer} `target` 中结束对比的偏移量（不包含）。
   当 `targetStart` 为 `undefined` 时忽略。
   **默认:** `target.length`
-* `sourceStart` {Integer} `buf` 中开始对比的偏移量。
+* `sourceStart` {integer} `buf` 中开始对比的偏移量。
   当 `targetStart` 为 `undefined` 时忽略。
   **默认:** `0`
-* `sourceEnd` {Integer} `buf` 中结束对比的偏移量（不包含）。
+* `sourceEnd` {integer} `buf` 中结束对比的偏移量（不包含）。
   当 `targetStart` 为 `undefined` 时忽略。
   **默认:** [`buf.length`]
-* 返回: {Integer}
+* 返回: {integer}
 
 比较 `buf` 与 `target`，返回表明 `buf` 在排序上是否排在 `target` 之前、或之后、或相同。
 对比是基于各自 `Buffer` 实际的字节序列。