docs: update contextIsolation documentation on access to globals (electron#19732)

samiskin · web-flow · commit ec85a91472a5 · 2020-11-18T15:24:00.000+09:00
diff --git a/docs/api/browser-window.md b/docs/api/browser-window.md
@@ -337,18 +337,17 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
       more details.
     * `contextIsolation` Boolean (optional) - Whether to run Electron APIs and
       the specified `preload` script in a separate JavaScript context. Defaults
-      to `false`. The context that the `preload` script runs in will still
-      have full access to the `document` and `window` globals but it will use
-      its own set of JavaScript builtins (`Array`, `Object`, `JSON`, etc.)
-      and will be isolated from any changes made to the global environment
-      by the loaded page. The Electron API will only be available in the
-      `preload` script and not the loaded page. This option should be used when
-      loading potentially untrusted remote content to ensure the loaded content
-      cannot tamper with the `preload` script and any Electron APIs being used.
-      This option uses the same technique used by [Chrome Content Scripts][chrome-content-scripts].
-      You can access this context in the dev tools by selecting the
-      'Electron Isolated Context' entry in the combo box at the top of the
-      Console tab.
+      to `false`. The context that the `preload` script runs in will only have
+      access to its own dedicated `document` and `window` globals, as well as
+      its own set of JavaScript builtins (`Array`, `Object`, `JSON`, etc.),
+      which are all invisible to the loaded content. The Electron API will only
+      be available in the `preload` script and not the loaded page. This option
+      should be used when loading potentially untrusted remote content to ensure
+      the loaded content cannot tamper with the `preload` script and any
+      Electron APIs being used.  This option uses the same technique used by
+      [Chrome Content Scripts][chrome-content-scripts].  You can access this
+      context in the dev tools by selecting the 'Electron Isolated Context'
+      entry in the combo box at the top of the Console tab.
     * `worldSafeExecuteJavaScript` Boolean (optional) - If true, values returned from `webFrame.executeJavaScript` will be sanitized to ensure JS values
       can't unsafely cross between worlds when using `contextIsolation`.  The default
       is `false`. In Electron 12, the default will be changed to `true`. _Deprecated_
diff --git a/docs/tutorial/security.md b/docs/tutorial/security.md
@@ -233,8 +233,8 @@ practice, that means that global objects like `Array.prototype.push` or
 Electron uses the same technology as Chromium's [Content Scripts](https://developer.chrome.com/extensions/content_scripts#execution-environment)
 to enable this behavior.
 
-Even when you use `nodeIntegration: false` to enforce strong isolation and
-prevent the use of Node primitives, `contextIsolation` must also be used.
+Even when `nodeIntegration: false` is used, to truly enforce strong isolation
+and prevent the use of Node primitives `contextIsolation` **must** also be used.
 
 ### Why & How?
 
