doc: update description of External

addaleax · codebytere · commit 63af1ab60f72 · 2020-03-16T19:40:43.000-07:00
The previous description did not mention what an `External` is and instead only provided some hints around what it is not. Update the description to be more accurate. PR-URL: #31255 Reviewed-By: Anto Aravinth <anto.aravinth.cse@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: David Carlier <devnexen@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>
diff --git a/doc/api/util.md b/doc/api/util.md
@@ -1391,11 +1391,12 @@ added: v10.0.0
 * Returns: {boolean}
 
 Returns `true` if the value is a native `External` value.
-A native `External` value is a special type of object whose
-data is not stored within the JavaScript managed heap
-and does not conform to standard JavaScript types. Such
-objects are created either by Node.js internals or native
-addons and are wrapped by a JavaScript object.
+
+A native `External` value is a special type of object that contains a
+raw C++ pointer (`void*`) for access from native code, and has no other
+properties. Such objects are created either by Node.js internals or native
+addons. In JavaScript, they are [frozen][`Object.freeze()`] objects with a
+`null` prototype.
 
 ### `util.types.isFloat32Array(value)`
 <!-- YAML
@@ -2318,6 +2319,7 @@ util.log('Timestamped message.');
 [`Int8Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Int8Array
 [`Map`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
 [`Object.assign()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign
+[`Object.freeze()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze
 [`Promise`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
 [`Proxy`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy
 [`Set`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
