diff --git a/docs/api/app.md b/docs/api/app.md index 740da22d82ee..14dc557e2374 100644 --- a/docs/api/app.md +++ b/docs/api/app.md @@ -881,7 +881,7 @@ Changes the [Application User Model ID][app-user-model-id] to `id`. Imports the certificate in pkcs12 format into the platform certificate store. `callback` is called with the `result` of import operation, a value of `0` -indicates success while any other value indicates failure according to chromium [net_error_list](https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h). +indicates success while any other value indicates failure according to Chromium [net_error_list](https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h). ### `app.disableHardwareAcceleration()` @@ -1033,7 +1033,7 @@ const stopAccessingSecurityScopedResource = app.startAccessingSecurityScopedReso stopAccessingSecurityScopedResource() ``` -Start accessing a security scoped resource. With this method electron applications that are packaged for the Mac App Store may reach outside their sandbox to access files chosen by the user. See [Apple's documentation](https://developer.apple.com/library/content/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW16) for a description of how this system works. +Start accessing a security scoped resource. With this method Electron applications that are packaged for the Mac App Store may reach outside their sandbox to access files chosen by the user. See [Apple's documentation](https://developer.apple.com/library/content/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW16) for a description of how this system works. ### `app.commandLine.appendSwitch(switch[, value])` diff --git a/docs/api/menu-item.md b/docs/api/menu-item.md index f687e43dbc9f..06d9cf4f9380 100644 --- a/docs/api/menu-item.md +++ b/docs/api/menu-item.md @@ -59,11 +59,11 @@ The `role` property can have following values: * `delete` * `minimize` - Minimize current window. * `close` - Close current window. -* `quit`- Quit the application. +* `quit` - Quit the application. * `reload` - Reload the current window. * `forceReload` - Reload the current window ignoring the cache. * `toggleDevTools` - Toggle developer tools in the current window. -* `toggleFullScreen`- Toggle full screen mode on the current window. +* `toggleFullScreen` - Toggle full screen mode on the current window. * `resetZoom` - Reset the focused page's zoom level to the original size. * `zoomIn` - Zoom in the focused page by 10%. * `zoomOut` - Zoom out the focused page by 10%. diff --git a/docs/api/sandbox-option.md b/docs/api/sandbox-option.md index 4923f93bbe6d..8a9d242fce0e 100644 --- a/docs/api/sandbox-option.md +++ b/docs/api/sandbox-option.md @@ -2,7 +2,7 @@ > Create a browser window with a renderer that can run inside Chromium OS sandbox. With this option enabled, the renderer must communicate via IPC to the main process in order to access node APIs. -However, in order to enable the Chromium OS sandbox, electron must be run with the `--enable-sandbox` +However, in order to enable the Chromium OS sandbox, Electron must be run with the `--enable-sandbox` command line argument. One of the key security features of Chromium is that all blink rendering/JavaScript @@ -14,26 +14,26 @@ to the system by delegating tasks to the main process via IPC. [Here's](https://www.chromium.org/developers/design-documents/sandbox) more information about the sandbox. -Since a major feature in electron is the ability to run node.js in the +Since a major feature in Electron is the ability to run Node.js in the renderer process (making it easier to develop desktop applications using web technologies), the sandbox is disabled by electron. This is because -most node.js APIs require system access. `require()` for example, is not +most Node.js APIs require system access. `require()` for example, is not possible without file system permissions, which are not available in a sandboxed environment. Usually this is not a problem for desktop applications since the code is always -trusted, but it makes electron less secure than chromium for displaying +trusted, but it makes Electron less secure than Chromium for displaying untrusted web content. For applications that require more security, the -`sandbox` flag will force electron to spawn a classic chromium renderer that is +`sandbox` flag will force Electron to spawn a classic Chromium renderer that is compatible with the sandbox. -A sandboxed renderer doesn't have a node.js environment running and doesn't -expose node.js JavaScript APIs to client code. The only exception is the preload script, -which has access to a subset of the electron renderer API. +A sandboxed renderer doesn't have a Node.js environment running and doesn't +expose Node.js JavaScript APIs to client code. The only exception is the preload script, +which has access to a subset of the Electron renderer API. Another difference is that sandboxed renderers don't modify any of the default JavaScript APIs. Consequently, some APIs such as `window.open` will work as they -do in chromium (i.e. they do not return a [`BrowserWindowProxy`](browser-window-proxy.md)). +do in Chromium (i.e. they do not return a [`BrowserWindowProxy`](browser-window-proxy.md)). ## Example @@ -51,9 +51,9 @@ app.on('ready', () => { }) ``` -In the above code the [`BrowserWindow`](browser-window.md) that was created has node.js disabled and can communicate -only via IPC. The use of this option stops electron from creating a node.js runtime in the renderer. Also, -within this new window `window.open` follows the native behaviour (by default electron creates a [`BrowserWindow`](browser-window.md) +In the above code the [`BrowserWindow`](browser-window.md) that was created has Node.js disabled and can communicate +only via IPC. The use of this option stops Electron from creating a Node.js runtime in the renderer. Also, +within this new window `window.open` follows the native behaviour (by default Electron creates a [`BrowserWindow`](browser-window.md) and returns a proxy to this via `window.open`). It is important to note that this option alone won't enable the OS-enforced sandbox. To enable this feature, the @@ -75,19 +75,19 @@ app.on('ready', () => { Note that it is not enough to call `app.commandLine.appendSwitch('--enable-sandbox')`, as electron/node startup -code runs after it is possible to make changes to chromium sandbox settings. The -switch must be passed to electron on the command-line: +code runs after it is possible to make changes to Chromium sandbox settings. The +switch must be passed to Electron on the command-line: ```sh electron --enable-sandbox app.js ``` It is not possible to have the OS sandbox active only for some renderers, if -`--enable-sandbox` is enabled, normal electron windows cannot be created. +`--enable-sandbox` is enabled, normal Electron windows cannot be created. If you need to mix sandboxed and non-sandboxed renderers in one application, omit the `--enable-sandbox` argument. Without this argument, windows -created with `sandbox: true` will still have node.js disabled and communicate +created with `sandbox: true` will still have Node.js disabled and communicate only via IPC, which by itself is already a gain from security POV. ## Preload @@ -112,7 +112,7 @@ and preload.js: ```js // This file is loaded whenever a javascript context is created. It runs in a -// private scope that can access a subset of electron renderer APIs. We must be +// private scope that can access a subset of Electron renderer APIs. We must be // careful to not leak any objects into the global scope! const fs = require('fs') const {ipcRenderer} = require('electron') @@ -136,7 +136,7 @@ window.open = customWindowOpen Important things to notice in the preload script: -- Even though the sandboxed renderer doesn't have node.js running, it still has +- Even though the sandboxed renderer doesn't have Node.js running, it still has access to a limited node-like environment: `Buffer`, `process`, `setImmediate` and `require` are available. - The preload script can indirectly access all APIs from the main process through the @@ -146,7 +146,7 @@ Important things to notice in the preload script: - The preload script must be contained in a single script, but it is possible to have complex preload code composed with multiple modules by using a tool like browserify, as explained below. In fact, browserify is already used by - electron to provide a node-like environment to the preload script. + Electron to provide a node-like environment to the preload script. To create a browserify bundle and use it as a preload script, something like the following should be used: @@ -178,7 +178,7 @@ following modules: - `timers` - `url` -More may be added as needed to expose more electron APIs in the sandbox, but any +More may be added as needed to expose more Electron APIs in the sandbox, but any module in the main process can already be used through `electron.remote.require`. @@ -186,7 +186,7 @@ module in the main process can already be used through Please use the `sandbox` option with care, as it is still an experimental feature. We are still not aware of the security implications of exposing some -electron renderer APIs to the preload script, but here are some things to +Electron renderer APIs to the preload script, but here are some things to consider before rendering untrusted content: - A preload script can accidentally leak privileged APIs to untrusted code. @@ -194,9 +194,9 @@ consider before rendering untrusted content: APIs, effectively granting full access to the system through the `remote` module. -Since rendering untrusted content in electron is still uncharted territory, +Since rendering untrusted content in Electron is still uncharted territory, the APIs exposed to the sandbox preload script should be considered more -unstable than the rest of electron APIs, and may have breaking changes to fix +unstable than the rest of Electron APIs, and may have breaking changes to fix security issues. One planned enhancement that should greatly increase security is to block IPC diff --git a/docs/api/structures/certificate-principal.md b/docs/api/structures/certificate-principal.md index 12c46382aaf3..2eb5574bffe0 100644 --- a/docs/api/structures/certificate-principal.md +++ b/docs/api/structures/certificate-principal.md @@ -1,8 +1,8 @@ # CertificatePrincipal Object -* `commonName` String - Common Name -* `organizations` String[] - Organization names -* `organizationUnits` String[] - Organization Unit names -* `locality` String - Locality -* `state` String - State or province -* `country` String - Country or region +* `commonName` String - Common Name. +* `organizations` String[] - Organization names. +* `organizationUnits` String[] - Organization Unit names. +* `locality` String - Locality. +* `state` String - State or province. +* `country` String - Country or region. diff --git a/docs/api/structures/gpu-feature-status.md b/docs/api/structures/gpu-feature-status.md index f7bf3933d6c4..b0e5b8d15165 100644 --- a/docs/api/structures/gpu-feature-status.md +++ b/docs/api/structures/gpu-feature-status.md @@ -1,18 +1,18 @@ # GPUFeatureStatus Object -* `2d_canvas` String - Canvas -* `flash_3d` String - Flash -* `flash_stage3d` String - Flash Stage3D -* `flash_stage3d_baseline` String - Flash Stage3D Baseline profile -* `gpu_compositing` String - Compositing -* `multiple_raster_threads` String - Multiple Raster Threads -* `native_gpu_memory_buffers` String - Native GpuMemoryBuffers -* `rasterization` String - Rasterization -* `video_decode` String - Video Decode -* `video_encode` String - Video Encode -* `vpx_decode` String - VPx Video Decode -* `webgl` String - WebGL -* `webgl2` String - WebGL2 +* `2d_canvas` String - Canvas. +* `flash_3d` String - Flash. +* `flash_stage3d` String - Flash Stage3D. +* `flash_stage3d_baseline` String - Flash Stage3D Baseline profile. +* `gpu_compositing` String - Compositing. +* `multiple_raster_threads` String - Multiple Raster Threads. +* `native_gpu_memory_buffers` String - Native GpuMemoryBuffers. +* `rasterization` String - Rasterization. +* `video_decode` String - Video Decode. +* `video_encode` String - Video Encode. +* `vpx_decode` String - VPx Video Decode. +* `webgl` String - WebGL. +* `webgl2` String - WebGL2. Possible values: diff --git a/docs/api/structures/mime-typed-buffer.md b/docs/api/structures/mime-typed-buffer.md index 08e5cd47a4a9..470dd3a3f7d7 100644 --- a/docs/api/structures/mime-typed-buffer.md +++ b/docs/api/structures/mime-typed-buffer.md @@ -1,4 +1,4 @@ # MimeTypedBuffer Object -* `mimeType` String - The mimeType of the Buffer that you are sending -* `data` Buffer - The actual Buffer content +* `mimeType` String - The mimeType of the Buffer that you are sending. +* `data` Buffer - The actual Buffer content. diff --git a/docs/api/structures/rectangle.md b/docs/api/structures/rectangle.md index 1a1228bc0b7c..9f7a000967d0 100644 --- a/docs/api/structures/rectangle.md +++ b/docs/api/structures/rectangle.md @@ -1,6 +1,6 @@ # Rectangle Object -* `x` Number - The x coordinate of the origin of the rectangle (must be an integer) -* `y` Number - The y coordinate of the origin of the rectangle (must be an integer) -* `width` Number - The width of the rectangle (must be an integer) -* `height` Number - The height of the rectangle (must be an integer) +* `x` Number - The x coordinate of the origin of the rectangle (must be an integer). +* `y` Number - The y coordinate of the origin of the rectangle (must be an integer). +* `width` Number - The width of the rectangle (must be an integer). +* `height` Number - The height of the rectangle (must be an integer). diff --git a/docs/api/structures/scrubber-item.md b/docs/api/structures/scrubber-item.md index 584593b6fde7..538579684242 100644 --- a/docs/api/structures/scrubber-item.md +++ b/docs/api/structures/scrubber-item.md @@ -1,4 +1,4 @@ # ScrubberItem Object -* `label` String (optional) - The text to appear in this item -* `icon` NativeImage (optional) - The image to appear in this item +* `label` String (optional) - The text to appear in this item. +* `icon` NativeImage (optional) - The image to appear in this item. diff --git a/docs/api/structures/segmented-control-segment.md b/docs/api/structures/segmented-control-segment.md index 06a8fd201a19..47dfaa240275 100644 --- a/docs/api/structures/segmented-control-segment.md +++ b/docs/api/structures/segmented-control-segment.md @@ -1,5 +1,5 @@ # SegmentedControlSegment Object -* `label` String (optional) - The text to appear in this segment -* `icon` NativeImage (optional) - The image to appear in this segment -* `enabled` Boolean (optional) - Whether this segment is selectable. Default: true +* `label` String (optional) - The text to appear in this segment. +* `icon` NativeImage (optional) - The image to appear in this segment. +* `enabled` Boolean (optional) - Whether this segment is selectable. Default: true. diff --git a/docs/api/structures/stream-protocol-response.md b/docs/api/structures/stream-protocol-response.md index 64847075a05e..ec1fa27e5e7d 100644 --- a/docs/api/structures/stream-protocol-response.md +++ b/docs/api/structures/stream-protocol-response.md @@ -1,5 +1,5 @@ # StreamProtocolResponse Object -* `statusCode` Number - The HTTP response code -* `headers` Object - An object containing the response headers -* `data` ReadableStream - A Node.js readable stream representing the response body +* `statusCode` Number - The HTTP response code. +* `headers` Object - An object containing the response headers. +* `data` ReadableStream - A Node.js readable stream representing the response body. diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md index 0740e7df6dca..9d5acd284db4 100644 --- a/docs/api/web-contents.md +++ b/docs/api/web-contents.md @@ -1468,7 +1468,7 @@ process. #### `contents.getProcessId()` -Returns `Integer` - The chromium internal `pid` of the associated renderer. Can +Returns `Integer` - The Chromium internal `pid` of the associated renderer. Can be compared to the `frameProcessId` passed by frame specific navigation events (e.g. `did-frame-navigate`) diff --git a/docs/api/web-frame.md b/docs/api/web-frame.md index c891bd5e5671..3d3e561e64a1 100644 --- a/docs/api/web-frame.md +++ b/docs/api/web-frame.md @@ -4,7 +4,7 @@ Process: [Renderer](../glossary.md#renderer-process) -`webFrame` export of the electron module is an instance of the `WebFrame` +`webFrame` export of the Electron module is an instance of the `WebFrame` class representing the top frame of the current `BrowserWindow`. Sub-frames can be retrieved by certain properties and methods (e.g. `webFrame.firstChild`). @@ -231,8 +231,8 @@ renderer process. current renderer process. Routing IDs can be retrieved from `WebFrame` instances (`webFrame.routingId`) and are also passed by frame specific `WebContents` navigation events (e.g. `did-frame-navigate`) - -Returns `WebFrame` - that has the supplied `routingId`, `null` if not found. + +Returns `WebFrame` - that has the supplied `routingId`, `null` if not found. ## Properties diff --git a/docs/development/build-instructions-gn.md b/docs/development/build-instructions-gn.md index 70c5d7a816b7..233939ab0767 100644 --- a/docs/development/build-instructions-gn.md +++ b/docs/development/build-instructions-gn.md @@ -87,7 +87,7 @@ this document :) ## Tests To run the tests, you'll first need to build the test modules against the -same version of node.js that was built as part of the build process. +same version of Node.js that was built as part of the build process. ```sh $ (cd electron/spec && npm i --nodedir=../../third_party/electron_node) diff --git a/docs/development/coding-style.md b/docs/development/coding-style.md index 870cb85c7f18..0abaea2417d7 100644 --- a/docs/development/coding-style.md +++ b/docs/development/coding-style.md @@ -40,7 +40,7 @@ etc. ## Documentation -* Write [remark](https://github.com/remarkjs/remark) markdown style +* Write [remark](https://github.com/remarkjs/remark) markdown style. You can run `npm run lint-docs` to ensure that your documentation changes are formatted correctly. diff --git a/docs/development/debugging-instructions-macos-xcode.md b/docs/development/debugging-instructions-macos-xcode.md index e136ee9253ce..6c2234477a35 100644 --- a/docs/development/debugging-instructions-macos-xcode.md +++ b/docs/development/debugging-instructions-macos-xcode.md @@ -1,12 +1,12 @@ ## Debugging with XCode ### Build Debug Electron with Release libchromiumcontent -You can create a debug build of electron by following [build instructions for macOS](build-instructions-osx.md). +You can create a debug build of Electron by following [build instructions for macOS](build-instructions-osx.md). The bootstrap process will download Release version of libchromiumcontent by default, -so you will not be able to step through the chromium source. +so you will not be able to step through the Chromium source. ### Build Debug Electron with Debug libchromiumcontent -If you want to debug and step through libchromiumcontent, you will have to run the +If you want to debug and step through libchromiumcontent, you will have to run the bootsrap script with the `--build_debug_libcc` argument. ```sh @@ -25,7 +25,7 @@ Electron debug builds will use this shared library to link against. ```sh $ ./script/build.py -c D --libcc ``` -This will build debug electron with debug version of libchromiumcontent. +This will build debug Electron with debug version of libchromiumcontent. ### Generate xcode project for debugging sources (cannot build code from xcode) Run the update script with the --xcode argument. @@ -37,16 +37,16 @@ to set breakpoints and inspect. ### Debugging and breakpoints -Launch electron app after build. -You can now open the xcode workspace created above and attach to the electron process +Launch Electron app after build. +You can now open the xcode workspace created above and attach to the Electron process through the Debug > Attach To Process > Electron debug menu. [Note: If you want to debug the renderer process, you need to attach to the Electron Helper as well.] You can now set breakpoints in any of the indexed files. However, you will not be able -to set breakpoints directly in the chromium source. -To set break points in the chromium source, you can choose Debug > Breakpoints > Create +to set breakpoints directly in the Chromium source. +To set break points in the Chromium source, you can choose Debug > Breakpoints > Create Symbolic Breakpoint and set any function name as the symbol. This will set the breakpoint for all functions with that name, from all the classes if there are more than one. You can also do this step of setting break points prior to attaching the debugger, however, actual breakpoints for symbolic breakpoint functions may not show up until the -debugger is attached to the app. \ No newline at end of file +debugger is attached to the app. diff --git a/docs/tutorial/application-distribution.md b/docs/tutorial/application-distribution.md index 83d7c7bdfe6a..22b861749cb9 100644 --- a/docs/tutorial/application-distribution.md +++ b/docs/tutorial/application-distribution.md @@ -141,7 +141,7 @@ we appreciate your help. 2. Create a new S3 bucket and create the following empty directory structure: ```sh - - atom-shell/ + - electron/ - symbols/ - dist/ ``` @@ -150,7 +150,7 @@ we appreciate your help. * `ELECTRON_GITHUB_TOKEN` - a token that can create releases on GitHub * `ELECTRON_S3_ACCESS_KEY`, `ELECTRON_S3_BUCKET`, `ELECTRON_S3_SECRET_KEY` - - the place where you'll upload node.js headers as well as symbols + the place where you'll upload Node.js headers as well as symbols * `ELECTRON_RELEASE` - Set to `true` and the upload part will run, leave unset and `surf-build` will do CI-type checks, appropriate to run for every pull request. diff --git a/docs/tutorial/electron-versioning.md b/docs/tutorial/electron-versioning.md index 5d7afaef428f..9629bb98282d 100644 --- a/docs/tutorial/electron-versioning.md +++ b/docs/tutorial/electron-versioning.md @@ -49,7 +49,7 @@ Below is a table explicitly mapping types of changes to their corresponding cate | Chromium version updates | | fix-related chromium patches | -Note that most chromium updates will be considered breaking. Fixes that can be backported will likely be cherry-picked as patches. +Note that most Chromium updates will be considered breaking. Fixes that can be backported will likely be cherry-picked as patches. # Stabilization Branches diff --git a/docs/tutorial/using-selenium-and-webdriver.md b/docs/tutorial/using-selenium-and-webdriver.md index 5df8818d5b83..1ceae13473af 100644 --- a/docs/tutorial/using-selenium-and-webdriver.md +++ b/docs/tutorial/using-selenium-and-webdriver.md @@ -164,7 +164,7 @@ To test your application without rebuilding Electron, [place](https://github.com/electron/electron/blob/master/docs/tutorial/application-distribution.md) your app source into Electron's resource directory. -Alternatively, pass an argument to run with your electron binary that points to +Alternatively, pass an argument to run with your Electron binary that points to your app's folder. This eliminates the need to copy-paste your app into Electron's resource directory.