mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: document modernization initiative more clearly (#17376)

Browse source 
* docs: document modernization initiative more clearly
This commit is contained in:
Shelley Vohr 2019-03-19 10:31:45 -07:00 committed by GitHub
parent 53f4af7722
commit 879462af4b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
18 changed files with 102 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/api/app.md
View file

@ -623,7 +623,7 @@ On _Windows_, there are 2 kinds of icons:
On _Linux_ and _macOS_, icons depend on the application associated with file mime type.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
### `app.getFileIcon(path[, options])`

2
docs/api/browser-window.md
View file

@ -1230,7 +1230,7 @@ Captures a snapshot of the page within `rect`. Upon completion `callback` will
be called with `callback(image)`. The `image` is an instance of [NativeImage](native-image.md)
that stores data of the snapshot. Omitting `rect` will capture the whole visible page.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
#### `win.capturePage([rect])`

8
docs/api/content-tracing.md
View file

@ -46,7 +46,7 @@ Get a set of category groups. The category groups can change as new code paths a
Once all child processes have acknowledged the `getCategories` request the `callback` is invoked with an array of category groups.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
### `contentTracing.getCategories()`
@ -66,7 +66,7 @@ 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.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
### `contentTracing.startRecording(options)`
@ -100,7 +100,7 @@ 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`.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
### `contentTracing.stopRecording(resultFilePath)`
@ -130,7 +130,7 @@ 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.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
### `contentTracing.getTraceBufferUsage()`

8
docs/api/cookies.md
View file

@ -99,7 +99,7 @@ the response.
Sends a request to get all cookies matching `filter`, `callback` will be called
with `callback(error, cookies)` on complete.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
#### `cookies.set(details)`
@ -142,7 +142,7 @@ Sets a cookie with `details`.
Sets a cookie with `details`, `callback` will be called with `callback(error)`
on complete.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
#### `cookies.remove(url, name)`
@ -162,7 +162,7 @@ Removes the cookies matching `url` and `name`
Removes the cookies matching `url` and `name`, `callback` will called with
`callback()` on complete.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
#### `cookies.flushStore()`
@ -176,4 +176,4 @@ Writes any unwritten cookies data to disk.
Writes any unwritten cookies data to disk.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**

2
docs/api/debugger.md
View file

@ -60,7 +60,7 @@ Detaches the debugger from the `webContents`.
Send given command to the debugging target.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
#### `debugger.sendCommand(method[, commandParams])`

2
docs/api/desktop-capturer.md
View file

@ -101,7 +101,7 @@ captured.
[`navigator.mediaDevices.getUserMedia`]: https://developer.mozilla.org/en/docs/Web/API/MediaDevices/getUserMedia
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
### `desktopCapturer.getSources(options)`

2
docs/api/dialog.md
View file

@ -335,7 +335,7 @@ On Windows the options are more limited, due to the Win32 APIs used:
* The `browserWindow` argument is ignored since it is not possible to make
this confirmation dialog modal.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
### `dialog.showCertificateTrustDialog([browserWindow, ]options)` _macOS_ _Windows_

4
docs/api/in-app-purchase.md
View file

@ -30,7 +30,7 @@ The `inAppPurchase` module has the following methods:
You should listen for the `transactions-updated` event as soon as possible and certainly before you call `purchaseProduct`.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
### `inAppPurchase.purchaseProduct(productID, quantity)`
@ -49,7 +49,7 @@ You should listen for the `transactions-updated` event as soon as possible and c
Retrieves the product descriptions.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
### `inAppPurchase.getProducts(productIDs)`

10
docs/api/modernization/overview.md Normal file
View file

@ -0,0 +1,10 @@
## Modernization
The Electron team is currently undergoing an initiative to modernize our API in a few concrete ways. These include: updating our modules to use idiomatic JS properties instead of separate `getPropertyX` and `setpropertyX`, converting callbacks to promises, and removing some other anti-patterns present in our APIs. The current status of the Promise intiative can be tracked in the [promisification](promisification.md) tracking file.
As we work to perform these updates, we seek to create the least disruptive amount of change at any given time, so as many changes as possible will be introduced in a backward compatible manner and deprecated after enough time has passed to give users a chance to upgrade their API calls.
This document and its child documents will be updated to reflect the latest status of our API changes.
* [Promisification](promisification.md)
* [Property Updates](property-updates.md)

0
docs/api/promisification.md → docs/api/modernization/promisification.md
View file

58
docs/api/modernization/property-updates.md Normal file
View file

@ -0,0 +1,58 @@
## Property Updates
The Electron team is currently undergoing an initiative to convert separate getter and setter functions in Electron to bespoke properties with `get` and `set` functionality. During this transition period, both the new properties and old getters and setters of these functions will work correctly and be documented.
## Candidates
* `app` module
* `accessibilitySupport`
* `badgeCount`
* `applicationMenu`
* `name`
* `dock`
* `badge`
* `autoUpdater` module
* `feedUrl`
* `BrowserWindow`
* `fullscreen`
* `simpleFullscreen`
* `movable`
* `resizable`
* `maximizable`
* `minimizable`
* `fullscreenable`
* `closable`
* `alwaysOnTop`
* `title`
* `documentEdited`
* `hasShadow`
* `autohideMenuBar`
* `menubarVisible`
* `visibleOnAllWorkspaces`
* `crashReporter` module
* `uploadToServer`
* `DownloadItem` class
* `savePath`
* `paused`
* `NativeImage`
* `templateImage`
* `Session` module
* `preloads`
* `SystemPreferences` module
* `appLevelAppearance`
* `webContents` module
* `zoomFactor`
* `zoomLevel`
* `audioMuted`
* `userAgent`
* `frameRate`
* `webFrame` modules
* `zoomFactor`
* `zoomLevel`
* `audioMuted`
* `<webview>`
* `zoomFactor`
* `zoomLevel`
* `audioMuted`
## Converted Properties

2
docs/api/net-log.md
View file

@ -35,7 +35,7 @@ Starts recording network events to `path`.
Stops recording network events. If not called, net logging will automatically end when app quits.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
### `netLog.stopLogging()`

2
docs/api/protocol.md
View file

@ -292,7 +292,7 @@ Unregisters the custom protocol of `scheme`.
The `callback` will be called with a boolean that indicates whether there is
already a handler for `scheme`.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
### `protocol.isProtocolHandled(scheme)`

16
docs/api/session.md
View file

@ -101,7 +101,7 @@ The following methods are available on instances of `Session`:
Callback is invoked with the session's current cache size.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
#### `ses.getCacheSize()`
@ -114,7 +114,7 @@ Returns `Promise<Integer>` - the session's current cache size, in bytes.
Clears the session’s HTTP cache.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
#### `ses.clearCache()`
@ -136,7 +136,7 @@ Clears the session’s HTTP cache.
Clears the storage data for the current session.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
#### `ses.clearStorageData([options])`
@ -231,7 +231,7 @@ The `proxyBypassRules` is a comma separated list of rules described below:
Match local addresses. The meaning of `<local>` is whether the
host matches one of: "127.0.0.1", "::1", "localhost".
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
#### `ses.setProxy(config)`
@ -319,7 +319,7 @@ The `proxyBypassRules` is a comma separated list of rules described below:
Resolves the proxy information for `url`. The `callback` will be called with
`callback(proxy)` when the request is performed.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
#### `ses.resolveProxy(url)`
@ -463,7 +463,7 @@ session.fromPartition('some-partition').setPermissionCheckHandler((webContents,
Clears the host resolver cache.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
#### `ses.clearHostResolverCache()`
@ -512,7 +512,7 @@ Returns `String` - The user agent for this session.
* `callback` Function
* `result` Buffer - Blob data.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
#### `ses.getBlobData(identifier)`
@ -546,7 +546,7 @@ the initial state will be `interrupted`. The download will start only when the
Clears the session’s HTTP authentication cache.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
#### `ses.clearAuthCache(options)`

6
docs/api/web-contents.md
View file

@ -980,7 +980,7 @@ contents.executeJavaScript('fetch("https://jsonplaceholder.typicode.com/users/1"
})
```
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
#### `contents.executeJavaScript(code[, userGesture])`
@ -1179,7 +1179,7 @@ Captures a snapshot of the page within `rect`. Upon completion `callback` will
be called with `callback(image)`. The `image` is an instance of [NativeImage](native-image.md)
that stores data of the snapshot. Omitting `rect` will capture the whole visible page.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
#### `contents.capturePage([rect])`
@ -1235,7 +1235,7 @@ settings.
The `callback` will be called with `callback(error, data)` on completion. The
`data` is a `Buffer` that contains the generated PDF data.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
#### `contents.printToPDF(options)`

4
docs/api/web-frame.md
View file

@ -123,7 +123,7 @@ In the browser window some HTML APIs like `requestFullScreen` can only be
invoked by a gesture from the user. Setting `userGesture` to `true` will remove
this limitation.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
### `webFrame.executeJavaScript(code[, userGesture])`
@ -152,7 +152,7 @@ or is rejected if the result of the code is a rejected promise.
Works like `executeJavaScript` but evaluates `scripts` in an isolated context.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
### `webFrame.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture])`

6
docs/api/webview-tag.md
View file

@ -392,7 +392,7 @@ Evaluates `code` in page. If `userGesture` is set, it will create the user
gesture context in the page. HTML APIs like `requestFullScreen`, which require
user action, can take advantage of this option for automation.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
### `<webview>.executeJavaScript(code[, userGesture])`
@ -563,7 +563,7 @@ Prints `webview`'s web page. Same as `webContents.print([options])`.
Prints `webview`'s web page as PDF, Same as `webContents.printToPDF(options, callback)`.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
### `<webview>.printToPDF(options)`
@ -591,7 +591,7 @@ Captures a snapshot of the page within `rect`. Upon completion `callback` will
be called with `callback(image)`. The `image` is an instance of [NativeImage](native-image.md)
that stores data of the snapshot. Omitting `rect` will capture the whole visible page.
**[Deprecated Soon](promisification.md)**
**[Deprecated Soon](modernization/promisification.md)**
### `<webview>.capturePage([rect])`

2
filenames.auto.gni
View file

@ -29,6 +29,7 @@ auto_filenames = {
"docs/api/locales.md",
"docs/api/menu-item.md",
"docs/api/menu.md",
"docs/api/modernization",
"docs/api/native-image.md",
"docs/api/net-log.md",
"docs/api/net.md",
@ -36,7 +37,6 @@ auto_filenames = {
"docs/api/power-monitor.md",
"docs/api/power-save-blocker.md",
"docs/api/process.md",
"docs/api/promisification.md",
"docs/api/protocol.md",
"docs/api/remote.md",
"docs/api/sandbox-option.md",