selection
')); ``` -**Note:** This API is experimental and could be removed in future. - -## clipboard.read(data[, type]) +### `clipboard.read(data[, type])` _Experimental_ * `data` String -* `type` String +* `type` String (optional) Reads `data` from the clipboard. -**Note:** This API is experimental and could be removed in future. - -## clipboard.write(data[, type]) +### `clipboard.write(data[, type])` * `data` Object * `text` String * `html` String * `image` [NativeImage](native-image.md) -* `type` String +* `type` String (optional) ```javascript var clipboard = require('clipboard'); clipboard.write({text: 'test', html: "test"}); ``` -Writes `data` into clipboard. +Writes `data` to the clipboard. diff --git a/docs/api/content-tracing.md b/docs/api/content-tracing.md index eab7b15d712..7d36fe9f5dd 100644 --- a/docs/api/content-tracing.md +++ b/docs/api/content-tracing.md @@ -1,12 +1,13 @@ -# content-tracing +# contentTracing -The `content-trace` module is used to collect tracing data generated by the +The `content-tracing` module is used to collect tracing data generated by the underlying Chromium content module. This module does not include a web interface -so you need to open `chrome://tracing/` in a Chrome browser and load the generated -file to view the result. +so you need to open `chrome://tracing/` in a Chrome browser and load the +generated file to view the result. ```javascript -var tracing = require('content-tracing'); +var contentTracing = require('content-tracing'); + tracing.startRecording('*', tracing.DEFAULT_OPTIONS, function() { console.log('Tracing started'); @@ -18,17 +19,21 @@ tracing.startRecording('*', tracing.DEFAULT_OPTIONS, function() { }); ``` -## tracing.getCategories(callback) +## Methods + +The `content-tracing` module has the following methods: + +### `contentTracing.getCategories(callback)` * `callback` Function Get a set of category groups. The category groups can change as new code paths are reached. -Once all child processes have acked to the `getCategories` request, `callback` -is invoked with an array of category groups. +Once all child processes have acknowledged the `getCategories` request the +`callback` is invoked with an array of category groups. -## tracing.startRecording(categoryFilter, traceOptions, callback) +### `contentTracing.startRecording(categoryFilter, traceOptions, callback)` * `categoryFilter` String * `traceOptions` String @@ -36,9 +41,9 @@ is invoked with an array of category groups. Start recording on all processes. -Recording begins immediately locally, and asynchronously on child processes -as soon as they receive the EnableRecording request. Once all child processes -have acked to the `startRecording` request, `callback` will be called back. +Recording begins immediately locally and asynchronously on child processes +as soon as they receive the EnableRecording request. The `callback` will be +called once all child processes have acknowledged the `startRecording` request. `categoryFilter` is a filter to control what category groups should be traced. A filter can have an optional `-` prefix to exclude category groups @@ -51,8 +56,8 @@ Examples: * `test_MyTest*,test_OtherStuff`, * `"-excluded_category1,-excluded_category2` -`traceOptions` controls what kind of tracing is enabled, it is a comma-delimited list. -Possible options are: +`traceOptions` controls what kind of tracing is enabled, it is a comma-delimited +list. Possible options are: * `record-until-full` * `record-continuously` @@ -62,34 +67,34 @@ Possible options are: The first 3 options are trace recoding modes and hence mutually exclusive. If more than one trace recording modes appear in the `traceOptions` string, -the last one takes precedence. If none of the trace recording mode is specified, -recording mode is `record-until-full`. +the last one takes precedence. If none of the trace recording modes are +specified, recording mode is `record-until-full`. -The trace option will first be reset to the default option (record_mode set to -`record-until-full`, enable_sampling and enable_systrace set to false) +The trace option will first be reset to the default option (`record_mode` set to +`record-until-full`, `enable_sampling` and `enable_systrace` set to `false`) before options parsed from `traceOptions` are applied on it. -## tracing.stopRecording(resultFilePath, callback) +### `contentTracing.stopRecording(resultFilePath, callback)` * `resultFilePath` String * `callback` Function Stop recording on all processes. -Child processes typically are caching trace data and only rarely flush and send -trace data back to the main process. That is because it may be an expensive -operation to send the trace data over IPC, and we would like to avoid much -runtime overhead of tracing. So, to end tracing, we must asynchronously ask all -child processes to flush any pending trace data. +Child processes typically cache trace data and only rarely flush and send +trace data back to the main process. This helps to minimize the runtime overhead +of tracing since sending trace data over IPC can be an expensive operation. So, +to end tracing, we must asynchronously ask all child processes to flush any +pending trace data. -Once all child processes have acked to the `stopRecording` request, `callback` -will be called back with a file that contains the traced data. +Once all child processes have acknowledged the `stopRecording` request, +`callback` will be called with a file that contains the traced data. -Trace data will be written into `resultFilePath` if it is not empty, or into a +Trace data will be written into `resultFilePath` if it is not empty or into a temporary file. The actual file path will be passed to `callback` if it's not -null. +`null`. -## tracing.startMonitoring(categoryFilter, traceOptions, callback) +### `contentTracing.startMonitoring(categoryFilter, traceOptions, callback)` * `categoryFilter` String * `traceOptions` String @@ -97,46 +102,47 @@ null. Start monitoring on all processes. -Monitoring begins immediately locally, and asynchronously on child processes as +Monitoring begins immediately locally and asynchronously on child processes as soon as they receive the `startMonitoring` request. -Once all child processes have acked to the `startMonitoring` request, -`callback` will be called back. +Once all child processes have acknowledged the `startMonitoring` request the +`callback` will be called. -## tracing.stopMonitoring(callback); +### `contentTracing.stopMonitoring(callback)` * `callback` Function Stop monitoring on all processes. -Once all child processes have acked to the `stopMonitoring` request, `callback` -is called back. +Once all child processes have acknowledged the `stopMonitoring` request the +`callback` is called. -## tracing.captureMonitoringSnapshot(resultFilePath, callback) +### `contentTracing.captureMonitoringSnapshot(resultFilePath, callback)` * `resultFilePath` String * `callback` Function Get the current monitoring traced data. -Child processes typically are caching trace data and only rarely flush and send -trace data back to the main process. That is because it may be an expensive -operation to send the trace data over IPC, and we would like to avoid unneeded -runtime overhead of tracing. So, to end tracing, we must asynchronously ask all -child processes to flush any pending trace data. +Child processes typically cache trace data and only rarely flush and send +trace data back to the main process. This is because it may be an expensive +operation to send the trace data over IPC and we would like to avoid unneeded +runtime overhead from tracing. So, to end tracing, we must asynchronously ask +all child processes to flush any pending trace data. -Once all child processes have acked to the `captureMonitoringSnapshot` request, -the `callback` will be invoked with a file that contains the traced data. +Once all child processes have acknowledged the `captureMonitoringSnapshot` +request the `callback` will be called with a file that contains the traced data. -## tracing.getTraceBufferUsage(callback) +### `contentTracing.getTraceBufferUsage(callback)` * `callback` Function -Get the maximum across processes of trace buffer percent full state. When the -TraceBufferUsage value is determined, the `callback` is called. +Get the maximum usage across processes of trace buffer as a percentage of the +full state. When the TraceBufferUsage value is determined the `callback` is +called. -## tracing.setWatchEvent(categoryName, eventName, callback) +### `contentTracing.setWatchEvent(categoryName, eventName, callback)` * `categoryName` String * `eventName` String @@ -145,7 +151,7 @@ TraceBufferUsage value is determined, the `callback` is called. `callback` will will be called every time the given event occurs on any process. -## tracing.cancelWatchEvent() +### `contentTracing.cancelWatchEvent()` -Cancel the watch event. If tracing is enabled, this may race with the watch -event callback. +Cancel the watch event. This may lead to a race condition with the watch event +callback if tracing is enabled. diff --git a/docs/api/crash-reporter.md b/docs/api/crash-reporter.md index da35008ea7f..86670fcc90c 100644 --- a/docs/api/crash-reporter.md +++ b/docs/api/crash-reporter.md @@ -1,9 +1,13 @@ -# crash-reporter +# crashReporter -The following is an example of automatically submitting a crash report to a remote server: +The `crash-reporter` module enables sending your app's crash reports. + +The following is an example of automatically submitting a crash report to a +remote server: ```javascript -crashReporter = require('crash-reporter'); +var crashReporter = require('crash-reporter'); + crashReporter.start({ productName: 'YourName', companyName: 'YourCompany', @@ -12,49 +16,60 @@ crashReporter.start({ }); ``` -## crashReporter.start(options) +## Methods -* `options` Object - * `productName` String, default: Electron - * `companyName` String, default: GitHub, Inc - * `submitUrl` String, default: http://54.249.141.255:1127/post - * URL that crash reports will be sent to as POST - * `autoSubmit` Boolean, default: true - * Send the crash report without user interaction - * `ignoreSystemCrashHandler` Boolean, default: false - * `extra` Object - * An object you can define that will be sent along with the report. - * Only string properties are sent correctly. - * Nested objects are not supported. +The `crash-reporter` module has the following methods: -Developers are required to call this method before using other `crashReporter` APIs. +### `crashReporter.start(options)` + +`options` Object, properties: + +* `productName` String, default: Electron. +* `companyName` String, default: GitHub, Inc. +* `submitUrl` String, default: http://54.249.141.255:1127/post. + * URL that crash reports will be sent to as POST. +* `autoSubmit` Boolean, default: `true`. + * Send the crash report without user interaction. +* `ignoreSystemCrashHandler` Boolean, default: `false`. +* `extra` Object + * An object you can define that will be sent along with the report. + * Only string properties are sent correctly. + * Nested objects are not supported. + +You are required to call this method before using other `crashReporter` +APIs. **Note:** On OS X, Electron uses a new `crashpad` client, which is different from `breakpad` on Windows and Linux. To enable the crash collection feature, -you are required to call `crashReporter.start` API to initialize `crashpad` in the -main process and in each renderer process from which you wish to collect crash reports. +you are required to call the `crashReporter.start` API to initialize `crashpad` +in the main process and in each renderer process from which you wish to collect +crash reports. -## crashReporter.getLastCrashReport() +### `crashReporter.getLastCrashReport()` Returns the date and ID of the last crash report. If no crash reports have been sent or the crash reporter has not been started, `null` is returned. -## crashReporter.getUploadedReports() +### `crashReporter.getUploadedReports()` -Returns all uploaded crash reports. Each report contains the date and uploaded ID. +Returns all uploaded crash reports. Each report contains the date and uploaded +ID. -# crash-reporter payload +## crash-reporter Payload The crash reporter will send the following data to the `submitUrl` as `POST`: -* `rept` String - e.g. 'electron-crash-service' -* `ver` String - The version of Electron -* `platform` String - e.g. 'win32' -* `process_type` String - e.g. 'renderer' +* `rept` String - e.g. 'electron-crash-service'. +* `ver` String - The version of Electron. +* `platform` String - e.g. 'win32'. +* `process_type` String - e.g. 'renderer'. * `ptime` Number -* `_version` String - The version in `package.json` -* `_productName` String - The product name in the `crashReporter` `options` object -* `prod` String - Name of the underlying product. In this case Electron -* `_companyName` String - The company name in the `crashReporter` `options` object -* `upload_file_minidump` File - The crashreport as file -* All level one properties of the `extra` object in the `crashReporter` `options` object +* `_version` String - The version in `package.json`. +* `_productName` String - The product name in the `crashReporter` `options` + object. +* `prod` String - Name of the underlying product. In this case Electron. +* `_companyName` String - The company name in the `crashReporter` `options` + object. +* `upload_file_minidump` File - The crash report as file. +* All level one properties of the `extra` object in the `crashReporter`. + `options` object