From db3cf52add2c88f99dc0b6c787ebbe801cc934c0 Mon Sep 17 00:00:00 2001 From: Samuel Attard Date: Fri, 26 Jul 2019 16:12:59 -0700 Subject: [PATCH] docs: add support for readonly,deprecated and platform doc annotations (#19478) --- docs/api/app.md | 10 +++++----- docs/api/browser-window.md | 4 ++-- docs/api/dialog.md | 4 ++-- docs/api/net-log.md | 4 ++-- docs/api/process.md | 18 +++++++++--------- docs/api/remote.md | 2 +- docs/api/session.md | 8 ++++---- docs/api/web-contents.md | 10 +++++----- docs/api/web-frame.md | 22 +++++++++++----------- lib/browser/api/app.ts | 2 +- package.json | 4 ++-- yarn.lock | 33 +++++++++------------------------ 12 files changed, 53 insertions(+), 68 deletions(-) diff --git a/docs/api/app.md b/docs/api/app.md index 8ef431cef..adeb14cd3 100644 --- a/docs/api/app.md +++ b/docs/api/app.md @@ -983,7 +983,7 @@ Updates the current activity if its type matches `type`, merging the entries fro Changes the [Application User Model ID][app-user-model-id] to `id`. -### `app.importCertificate(options, callback)` _LINUX_ +### `app.importCertificate(options, callback)` _Linux_ * `options` Object * `certificate` String - Path for the pkcs12 file. @@ -1193,7 +1193,7 @@ Returns `Boolean` - whether or not the current OS version allows for native emoj Show the platform's native emoji picker. -### `app.startAccessingSecurityScopedResource(bookmarkData)` _macOS (mas)_ +### `app.startAccessingSecurityScopedResource(bookmarkData)` _mas_ * `bookmarkData` String - The base64 encoded security scoped bookmark data returned by the `dialog.showOpenDialog` or `dialog.showSaveDialog` methods. @@ -1287,17 +1287,17 @@ On macOS, setting this with any nonzero integer shows on the dock icon. On Linux **Note:** Unity launcher requires the existence of a `.desktop` file to work, for more information please read [Desktop Environment Integration][unity-requirement]. -### `app.commandLine` +### `app.commandLine` _Readonly_ A [`CommandLine`](./command-line.md) object that allows you to read and manipulate the command line arguments that Chromium uses. -### `app.dock` _macOS_ +### `app.dock` _macOS_ _Readonly_ A [`Dock`](./dock.md) object that allows you to perform actions on your app icon in the user's dock on macOS. -### `app.isPackaged` +### `app.isPackaged` _Readonly_ A `Boolean` property that returns `true` if the app is packaged, `false` otherwise. For many apps, this property can be used to distinguish development and production environments. diff --git a/docs/api/browser-window.md b/docs/api/browser-window.md index 76fd609ab..35cac5aad 100644 --- a/docs/api/browser-window.md +++ b/docs/api/browser-window.md @@ -750,7 +750,7 @@ let win = new BrowserWindow({ width: 800, height: 600 }) win.loadURL('https://github.com') ``` -#### `win.webContents` +#### `win.webContents` _Readonly_ A `WebContents` object this window owns. All web page related events and operations will be done via it. @@ -758,7 +758,7 @@ operations will be done via it. See the [`webContents` documentation](web-contents.md) for its methods and events. -#### `win.id` +#### `win.id` _Readonly_ A `Integer` property representing the unique ID of the window. diff --git a/docs/api/dialog.md b/docs/api/dialog.md index 356621d74..07404cf86 100644 --- a/docs/api/dialog.md +++ b/docs/api/dialog.md @@ -50,7 +50,7 @@ The `dialog` module has the following methods: as a directory instead of a file. * `message` String (optional) _macOS_ - Message to display above input boxes. - * `securityScopedBookmarks` Boolean (optional) _masOS_ _mas_ - Create [security scoped bookmarks](https://developer.apple.com/library/content/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW16) when packaged for the Mac App Store. + * `securityScopedBookmarks` Boolean (optional) _macOS_ _mas_ - Create [security scoped bookmarks](https://developer.apple.com/library/content/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW16) when packaged for the Mac App Store. The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal. @@ -110,7 +110,7 @@ dialog.showOpenDialogSync(mainWindow, { as a directory instead of a file. * `message` String (optional) _macOS_ - Message to display above input boxes. - * `securityScopedBookmarks` Boolean (optional) _masOS_ _mas_ - Create [security scoped bookmarks](https://developer.apple.com/library/content/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW16) when packaged for the Mac App Store. + * `securityScopedBookmarks` Boolean (optional) _macOS_ _mas_ - Create [security scoped bookmarks](https://developer.apple.com/library/content/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW16) when packaged for the Mac App Store. Returns `Promise` - Resolve with an object containing the following: diff --git a/docs/api/net-log.md b/docs/api/net-log.md index 6d024347a..bdf1ade15 100644 --- a/docs/api/net-log.md +++ b/docs/api/net-log.md @@ -46,10 +46,10 @@ Stops recording network events. If not called, net logging will automatically en ## Properties -### `netLog.currentlyLogging` +### `netLog.currentlyLogging` _Readonly_ A `Boolean` property that indicates whether network logs are recorded. -### `netLog.currentlyLoggingPath` **Deprecated** +### `netLog.currentlyLoggingPath` _Readonly_ _Deprecated_ A `String` property that returns the path to the current log file. diff --git a/docs/api/process.md b/docs/api/process.md index 640393e74..924189754 100644 --- a/docs/api/process.md +++ b/docs/api/process.md @@ -56,17 +56,17 @@ process.once('loaded', () => { ## Properties -### `process.defaultApp` +### `process.defaultApp` _Readonly_ A `Boolean`. When app is started by being passed as parameter to the default app, this property is `true` in the main process, otherwise it is `undefined`. -### `process.isMainFrame` +### `process.isMainFrame` _Readonly_ A `Boolean`, `true` when the current renderer context is the "main" renderer frame. If you want the ID of the current frame you should use `webFrame.routingId`. -### `process.mas` +### `process.mas` _Readonly_ A `Boolean`. For Mac App Store build, this property is `true`, for other builds it is `undefined`. @@ -88,11 +88,11 @@ A `Boolean` that controls whether or not deprecation warnings are printed to `st formerly callback-based APIs converted to Promises are invoked using callbacks. Setting this to `true` will enable deprecation warnings. -### `process.resourcesPath` +### `process.resourcesPath` _Readonly_ A `String` representing the path to the resources directory. -### `process.sandboxed` +### `process.sandboxed` _Readonly_ A `Boolean`. When the renderer process is sandboxed, this property is `true`, otherwise it is `undefined`. @@ -115,19 +115,19 @@ A `Boolean` that controls whether or not process warnings printed to `stderr` in (including deprecations). This property is instead of the `--trace-warnings` command line flag. -### `process.type` +### `process.type` _Readonly_ A `String` representing the current process's type, can be `"browser"` (i.e. main process), `"renderer"`, or `"worker"` (i.e. web worker). -### `process.versions.chrome` +### `process.versions.chrome` _Readonly_ A `String` representing Chrome's version string. -### `process.versions.electron` +### `process.versions.electron` _Readonly_ A `String` representing Electron's version string. -### `process.windowsStore` +### `process.windowsStore` _Readonly_ A `Boolean`. If the app is running as a Windows Store app (appx), this property is `true`, for otherwise it is `undefined`. diff --git a/docs/api/remote.md b/docs/api/remote.md index 374be7875..e49e738ff 100644 --- a/docs/api/remote.md +++ b/docs/api/remote.md @@ -199,7 +199,7 @@ process. ## Properties -### `remote.process` +### `remote.process` _Readonly_ A `NodeJS.Process` object. The `process` object in the main process. This is the same as `remote.getGlobal('process')` but is cached. diff --git a/docs/api/session.md b/docs/api/session.md index a38737d39..82da931e9 100644 --- a/docs/api/session.md +++ b/docs/api/session.md @@ -427,15 +427,15 @@ registered. The following properties are available on instances of `Session`: -#### `ses.cookies` +#### `ses.cookies` _Readonly_ A [`Cookies`](cookies.md) object for this session. -#### `ses.webRequest` +#### `ses.webRequest` _Readonly_ A [`WebRequest`](web-request.md) object for this session. -#### `ses.protocol` +#### `ses.protocol` _Readonly_ A [`Protocol`](protocol.md) object for this session. @@ -454,7 +454,7 @@ app.on('ready', function () { }) ``` -#### `ses.netLog` +#### `ses.netLog` _Readonly_ A [`NetLog`](net-log.md) object for this session. diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md index ab337525c..13117882b 100644 --- a/docs/api/web-contents.md +++ b/docs/api/web-contents.md @@ -1760,26 +1760,26 @@ Only values between 1 and 60 are accepted. Only applicable if *offscreen rendering* is enabled. -#### `contents.id` +#### `contents.id` _Readonly_ A `Integer` representing the unique ID of this WebContents. -#### `contents.session` +#### `contents.session` _Readonly_ A [`Session`](session.md) used by this webContents. -#### `contents.hostWebContents` +#### `contents.hostWebContents` _Readonly_ A [`WebContents`](web-contents.md) instance that might own this `WebContents`. -#### `contents.devToolsWebContents` +#### `contents.devToolsWebContents` _Readonly_ A `WebContents` of DevTools for this `WebContents`. **Note:** Users should never store this object because it may become `null` when the DevTools has been closed. -#### `contents.debugger` +#### `contents.debugger` _Readonly_ A [`Debugger`](debugger.md) instance for this webContents. diff --git a/docs/api/web-frame.md b/docs/api/web-frame.md index 5354dd0b1..712aca439 100644 --- a/docs/api/web-frame.md +++ b/docs/api/web-frame.md @@ -228,35 +228,35 @@ Returns `WebFrame` - that has the supplied `routingId`, `null` if not found. ## Properties -### `webFrame.top` +### `webFrame.top` _Readonly_ -A `WebFrame` representing top frame in frame hierarchy to which `webFrame` +A `WebFrame | null` representing top frame in frame hierarchy to which `webFrame` belongs, the property would be `null` if top frame is not in the current renderer process. -### `webFrame.opener` +### `webFrame.opener` _Readonly_ -A `WebFrame` representing the frame which opened `webFrame`, the property would +A `WebFrame | null` representing the frame which opened `webFrame`, the property would be `null` if there's no opener or opener is not in the current renderer process. -### `webFrame.parent` +### `webFrame.parent` _Readonly_ -A `WebFrame` representing parent frame of `webFrame`, the property would be +A `WebFrame | null` representing parent frame of `webFrame`, the property would be `null` if `webFrame` is top or parent is not in the current renderer process. -### `webFrame.firstChild` +### `webFrame.firstChild` _Readonly_ -A `WebFrame` representing the first child frame of `webFrame`, the property +A `WebFrame | null` representing the first child frame of `webFrame`, the property would be `null` if `webFrame` has no children or if first child is not in the current renderer process. -### `webFrame.nextSibling` +### `webFrame.nextSibling` _Readonly_ -A `WebFrame` representing next sibling frame, the property would be `null` if +A `WebFrame | null` representing next sibling frame, the property would be `null` if `webFrame` is the last frame in its parent or if the next sibling is not in the current renderer process. -### `webFrame.routingId` +### `webFrame.routingId` _Readonly_ An `Integer` representing the unique frame id in the current renderer process. Distinct WebFrame instances that refer to the same underlying frame will have diff --git a/lib/browser/api/app.ts b/lib/browser/api/app.ts index 36320d94e..da9fa4cdd 100644 --- a/lib/browser/api/app.ts +++ b/lib/browser/api/app.ts @@ -37,7 +37,7 @@ Object.defineProperty(app, 'applicationMenu', { } }) -app.isPackaged = (() => { +App.prototype.isPackaged = (() => { const execFile = path.basename(process.execPath).toLowerCase() if (process.platform === 'win32') { return execFile !== 'electron.exe' diff --git a/package.json b/package.json index 5642df02c..fda157bf6 100644 --- a/package.json +++ b/package.json @@ -4,8 +4,8 @@ "repository": "https://github.com/electron/electron", "description": "Build cross platform desktop apps with JavaScript, HTML, and CSS", "devDependencies": { - "@electron/docs-parser": "^0.3.0", - "@electron/typescript-definitions": "^8.3.5", + "@electron/docs-parser": "^0.4.1", + "@electron/typescript-definitions": "^8.5.0", "@octokit/rest": "^16.3.2", "@primer/octicons": "^9.1.1", "@types/chai": "^4.1.7", diff --git a/yarn.lock b/yarn.lock index 87b652aae..3dd4159c5 100644 --- a/yarn.lock +++ b/yarn.lock @@ -25,10 +25,10 @@ dependencies: regenerator-runtime "^0.13.2" -"@electron/docs-parser@^0.2.1": - version "0.2.2" - resolved "https://registry.yarnpkg.com/@electron/docs-parser/-/docs-parser-0.2.2.tgz#7c9acd6cc10559c86a27bb0653ec13df10955f02" - integrity sha512-FKXktu5i6cHL+AkvWv34j2lpBXNpqfHN7YwhswcBqRFXsj24phpih/sY2NKx6OrFP9R3ReJeg681/luAf/3k8Q== +"@electron/docs-parser@^0.4.1": + version "0.4.1" + resolved "https://registry.yarnpkg.com/@electron/docs-parser/-/docs-parser-0.4.1.tgz#e6557a6a3899ca1168b9f2d70ad24d9ba924e4a9" + integrity sha512-mn4ofEvH8HNdzRMb++cUbiTkO88BAKwM0yjED3KrQ07yEl7CU1lK13qSMVSRhDzNkbg4kFTqBDjaJ57fdHlkxQ== dependencies: "@types/markdown-it" "^0.0.7" chai "^4.2.0" @@ -40,27 +40,12 @@ ora "^3.4.0" pretty-ms "^5.0.0" -"@electron/docs-parser@^0.3.0": - version "0.3.0" - resolved "https://registry.yarnpkg.com/@electron/docs-parser/-/docs-parser-0.3.0.tgz#cf8c33ed9cebffe7f3463a1e2d60ccf457b52ec6" - integrity sha512-/q2et0q6eMDItzv1ZCAH5ZJZY8AFGFkK1+wfAJfdarMDJOVs29pH8b0HjTXo2k+kLGlbC2TROZfuCHRgx+l/EQ== +"@electron/typescript-definitions@^8.5.0": + version "8.5.0" + resolved "https://registry.yarnpkg.com/@electron/typescript-definitions/-/typescript-definitions-8.5.0.tgz#8be8d90e2245478368180795b3632db02e90ccdc" + integrity sha512-sq7tTIyQyGMxrSbmCsbpyfV5Yc68Pb74rp5cbpaS3Kopi5sAL2nIi4TdTakVE7Pp4cye75i8HqDUBhsMpt+TvA== dependencies: - "@types/markdown-it" "^0.0.7" - chai "^4.2.0" - chalk "^2.4.2" - fs-extra "^7.0.1" - lodash.camelcase "^4.3.0" - markdown-it "^8.4.2" - minimist "^1.2.0" - ora "^3.4.0" - pretty-ms "^5.0.0" - -"@electron/typescript-definitions@^8.3.5": - version "8.4.0" - resolved "https://registry.yarnpkg.com/@electron/typescript-definitions/-/typescript-definitions-8.4.0.tgz#934b8b0b4433245794686f416398fc2503742f35" - integrity sha512-P+j99jjv7KD54p/nbrG3esPJzTq1fkK+MAuK+AnaU395Z6+5IRiXutLPFaO9i1idXg2Y3aknad0HKke4jQJB1Q== - dependencies: - "@electron/docs-parser" "^0.2.1" + "@electron/docs-parser" "^0.4.1" "@types/node" "^11.13.7" chalk "^2.4.2" colors "^1.1.2"