From 940911d5e630f31d1b7b0fd4bc8cc3fbd11cbb86 Mon Sep 17 00:00:00 2001
From: Franziska Hinkelmann <franziska.hinkelmann@gmail.com>
Date: Tue, 7 Nov 2017 18:22:23 +0100
Subject: [PATCH] doc: improve documentation for the vm module

Add an intro section and example for the vm module.

PR-URL: https://github.com/nodejs/node/pull/16867
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
---
 doc/api/vm.md | 32 ++++++++++++++++++++++++++++----
 1 file changed, 28 insertions(+), 4 deletions(-)

diff --git a/doc/api/vm.md b/doc/api/vm.md
index 592c78148e7040..408a2f4fdfbebb 100644
--- a/doc/api/vm.md
+++ b/doc/api/vm.md
@@ -7,14 +7,38 @@
 <!--name=vm-->
 
 The `vm` module provides APIs for compiling and running code within V8 Virtual
-Machine contexts. It can be accessed using:
+Machine contexts.
+
+JavaScript code can be compiled and run immediately or
+compiled, saved, and run later.
+
+A common use case is to run the code in a sandboxed environment.
+The sandboxed code uses a different V8 Context, meaning that
+it has a different global object than the rest of the code.
+
+One can provide the context by ["contextifying"][contextified] a sandbox
+object. The sandboxed code treats any property on the sandbox like a
+global variable. Any changes on global variables caused by the sandboxed
+code are reflected in the sandbox object.
 
 ```js
 const vm = require('vm');
-```
 
-JavaScript code can be compiled and run immediately or compiled, saved, and run
-later.
+const x = 1;
+
+const sandbox = { x: 2 };
+vm.createContext(sandbox); // Contextify the sandbox.
+
+const code = 'x += 40; var y = 17;';
+// x and y are global variables in the sandboxed environment.
+// Initially, x has the value 2 because that is the value of sandbox.x.
+vm.runInContext(code, sandbox);
+
+console.log(sandbox.x); // 42
+console.log(sandbox.y); // 17
+
+console.log(x); // 1; y is not defined.
+```
 
 *Note*: The vm module is not a security mechanism.
 **Do not use it to run untrusted code**.