Merge pull request #2585 from atom/jl-std-docs-2
Standardize: clipboard, content-tracing, crash-reporter
This commit is contained in:
Jessica Lord
commit
609961a1de
3 changed files with 140 additions and 115 deletions
|
|
@ -1,7 +1,7 @@
|
|||
# clipboard
|
||||
|
||||
The `clipboard` provides methods to perform copy and paste operations. The following example
|
||||
shows how to write a string to the clipboard:
|
||||
The `clipboard` module provides methods to perform copy and paste operations.
|
||||
The following example shows how to write a string to the clipboard:
|
||||
|
||||
```javascript
|
||||
var clipboard = require('clipboard');
|
||||
|
|
@ -17,59 +17,67 @@ clipboard.writeText('Example String', 'selection');
|
|||
console.log(clipboard.readText('selection'));
|
||||
```
|
||||
|
||||
## clipboard.readText([type])
|
||||
## Methods
|
||||
|
||||
* `type` String
|
||||
The `clipboard` module has the following methods:
|
||||
|
||||
**Note:** Experimental APIs are marked as such and could be removed in future.
|
||||
|
||||
### `clipboard.readText([type])`
|
||||
|
||||
* `type` String (optional)
|
||||
|
||||
Returns the content in the clipboard as plain text.
|
||||
|
||||
## clipboard.writeText(text[, type])
|
||||
### `clipboard.writeText(text[, type])`
|
||||
|
||||
* `text` String
|
||||
* `type` String
|
||||
* `type` String (optional)
|
||||
|
||||
Writes the `text` into the clipboard as plain text.
|
||||
|
||||
## clipboard.readHtml([type])
|
||||
### `clipboard.readHtml([type])`
|
||||
|
||||
* `type` String
|
||||
* `type` String (optional)
|
||||
|
||||
Returns the content in the clipboard as markup.
|
||||
|
||||
## clipboard.writeHtml(markup[, type])
|
||||
### `clipboard.writeHtml(markup[, type])`
|
||||
|
||||
* `markup` String
|
||||
* `type` String
|
||||
* `type` String (optional)
|
||||
|
||||
Writes `markup` into the clipboard.
|
||||
Writes `markup` to the clipboard.
|
||||
|
||||
## clipboard.readImage([type])
|
||||
### `clipboard.readImage([type])`
|
||||
|
||||
* `type` String
|
||||
* `type` String (optional)
|
||||
|
||||
Returns the content in the clipboard as a [NativeImage](native-image.md).
|
||||
|
||||
## clipboard.writeImage(image[, type])
|
||||
### `clipboard.writeImage(image[, type])`
|
||||
|
||||
* `image` [NativeImage](native-image.md)
|
||||
* `type` String
|
||||
* `type` String (optional)
|
||||
|
||||
Writes `image` into the clipboard.
|
||||
Writes `image` to the clipboard.
|
||||
|
||||
## clipboard.clear([type])
|
||||
### `clipboard.clear([type])`
|
||||
|
||||
* `type` String
|
||||
* `type` String (optional)
|
||||
|
||||
Clears the clipboard.
|
||||
Clears the clipboard content.
|
||||
|
||||
## clipboard.availableFormats([type])
|
||||
### `clipboard.availableFormats([type])`
|
||||
|
||||
Returns an array of supported `format` for the clipboard `type`.
|
||||
* `type` String (optional)
|
||||
|
||||
## clipboard.has(data[, type])
|
||||
Returns an array of supported formats for the clipboard `type`.
|
||||
|
||||
### `clipboard.has(data[, type])` _Experimental_
|
||||
|
||||
* `data` String
|
||||
* `type` String
|
||||
* `type` String (optional)
|
||||
|
||||
Returns whether the clipboard supports the format of specified `data`.
|
||||
|
||||
|
|
@ -78,27 +86,23 @@ var clipboard = require('clipboard');
|
|||
console.log(clipboard.has('<p>selection</p>'));
|
||||
```
|
||||
|
||||
**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: "<b>test</b>"});
|
||||
```
|
||||
Writes `data` into clipboard.
|
||||
Writes `data` to the clipboard.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue