docs: Improved documentation (#13403)

This commit is contained in:
Tiago Danin 2018-07-20 14:58:19 -03:00 committed by Shelley Vohr
parent 2440d03595
commit 1fd6d38a0a
18 changed files with 79 additions and 79 deletions

View file

@ -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])`

View file

@ -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%.

View file

@ -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

View file

@ -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.

View file

@ -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:

View file

@ -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.

View file

@ -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).

View file

@ -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.

View file

@ -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.

View file

@ -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.

View file

@ -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`)

View file

@ -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

View file

@ -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)

View file

@ -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.

View file

@ -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.
debugger is attached to the app.

View file

@ -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.

View file

@ -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

View file

@ -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.