doc: general improvements to v8.md copy

PR-URL: https://github.com/nodejs/node/pull/6829
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Michaël Zasso <mic.besace@gmail.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>

1 files changed, 33 insertions, 11 deletions

diff --git a/doc/api/v8.md b/doc/api/v8.md
index b745ac92ba..a589a0fbb1 100644
--- a/doc/api/v8.md
+++ b/doc/api/v8.md
@@ -1,17 +1,29 @@
 # V8
 
-    Stability: 2 - Stable
+The `v8` module exposes APIs that are specific to the version of [V8][]
+built into the Node.js binary. It can be accessed using:
 
-This module exposes events and interfaces specific to the version of [V8][]
-built with Node.js.  These interfaces are subject to change by upstream and are
-therefore not covered under the stability index.
+```js
+const v8 = require('v8');
+```
+
+*Note*: The APIs and implementation are subject to change at any time.
 
 ## v8.getHeapStatistics()
 <!-- YAML
 added: v1.0.0
 -->
 
-Returns an object with the following properties
+Returns an object with the following properties:
+
+* `total_heap_size` {number}
+* `total_heap_size_executable` {number}
+* `total_physical_size` {number}
+* `total_available_size` {number}
+* `used_heap_size` {number}
+* `heap_size_limit` {number}
+
+For example:
 
 ```js
 {
@@ -30,11 +42,19 @@ added: v6.0.0
 -->
 
 Returns statistics about the V8 heap spaces, i.e. the segments which make up
-the V8 heap. Order of heap spaces nor availability of a heap space can be
-guaranteed as the statistics are provided via the V8 `GetHeapSpaceStatistics`
-function.
+the V8 heap. Neither the ordering of heap spaces, nor the availability of a
+heap space can be guaranteed as the statistics are provided via the V8
+[`GetHeapSpaceStatistics`][] function and may change from one V8 version to the
+next.
+
+The value returned is an array of objects containing the following properties:
+* `space_name` {string}
+* `space_size` {number}
+* `space_used_size` {number}
+* `space_available_size` {number}
+* `physical_space_size` {number}
 
-Example result:
+For example:
 
 ```
 [
@@ -81,9 +101,10 @@ Example result:
 added: v1.0.0
 -->
 
-Set additional V8 command line flags.  Use with care; changing settings
+The `v8.setFlagsFromString()` method can be used to programmatically set 
+V8 command line flags. This method should be used with care. Changing settings
 after the VM has started may result in unpredictable behavior, including
-crashes and data loss.  Or it may simply do nothing.
+crashes and data loss; or it may simply do nothing.
 
 The V8 options available for a version of Node.js may be determined by running
 `node --v8-options`.  An unofficial, community-maintained list of options
@@ -100,3 +121,4 @@ setTimeout(function() { v8.setFlagsFromString('--notrace_gc'); }, 60e3);
 
 [V8]: https://developers.google.com/v8/
 [here]: https://github.com/thlorenz/v8-flags/blob/master/flags-0.11.md
+[`GetHeapSpaceStatistics`]: https://v8docs.nodesource.com/node-5.0/d5/dda/classv8_1_1_isolate.html#ac673576f24fdc7a33378f8f57e1d13a4