doc: general improvements to v8.md copy

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');
+```
+
+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