fix: ensure the typescript definitions only export correct value types (

electron#28712) * fix: ensure the typescript definitions only export correct value types In typescript there are two main types of "types" you can export, value types (class, const) and definition types (type, interface). The typescript compiler will let anything declared via const or class be used as a value. Unfortunately we were exporting a bunch of things (see the diff) as class/const when they weren't actually exported values. This lead to typescript being happy but the runtime throwing errors (not something we want). This change passes "exported-in" context through our docs, to the parser and then to the definitions generator to ensure we only mark things as exported in the ts defs that we actually export. Fixes electron#22167 * chore: update typescript-defs * chore: update typescript-defs * chore: fix bad typescript in IPC test * docs: test rendering of new syntax * chore: update per feedback, use same syntax but with 'this is not exportedd' line
BlackHole1 · Aug 27, 2021 · 16c3ba9 · 16c3ba9
1 parent d5ce03c
commit 16c3ba9
Show file tree

Hide file tree

Showing 30 changed files with 68 additions and 39 deletions.
diff --git a/.markdownlint.json b/.markdownlint.json
@@ -22,5 +22,8 @@
   "no-trailing-spaces": {
     "br_spaces": 0
   },
-  "single-h1": false
+  "single-h1": false,
+  "no-inline-html": {
+    "allowed_elements": ["br"]
+  }
 }
diff --git a/docs/api/browser-window-proxy.md b/docs/api/browser-window-proxy.md
@@ -2,7 +2,8 @@
 
 > Manipulate the child browser window
 
-Process: [Renderer](../glossary.md#renderer-process)
+Process: [Renderer](../glossary.md#renderer-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 The `BrowserWindowProxy` object is returned from `window.open` and provides
 limited functionality with the child window.

diff --git a/docs/api/client-request.md b/docs/api/client-request.md
@@ -2,7 +2,8 @@
 
 > Make HTTP/HTTPS requests.
 
-Process: [Main](../glossary.md#main-process)
+Process: [Main](../glossary.md#main-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 `ClientRequest` implements the [Writable Stream](https://nodejs.org/api/stream.html#stream_writable_streams)
 interface and is therefore an [EventEmitter][event-emitter].

diff --git a/docs/api/command-line.md b/docs/api/command-line.md
@@ -2,7 +2,8 @@
 
 > Manipulate the command line arguments for your app that Chromium reads
 
-Process: [Main](../glossary.md#main-process)
+Process: [Main](../glossary.md#main-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 The following example shows how to check if the `--disable-gpu` flag is set.
 

diff --git a/docs/api/cookies.md b/docs/api/cookies.md
@@ -2,7 +2,8 @@
 
 > Query and modify a session's cookies.
 
-Process: [Main](../glossary.md#main-process)
+Process: [Main](../glossary.md#main-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 Instances of the `Cookies` class are accessed by using `cookies` property of
 a `Session`.

diff --git a/docs/api/debugger.md b/docs/api/debugger.md
@@ -2,7 +2,8 @@
 
 > An alternate transport for Chrome's remote debugging protocol.
 
-Process: [Main](../glossary.md#main-process)
+Process: [Main](../glossary.md#main-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 Chrome Developer Tools has a [special binding][rdp] available at JavaScript
 runtime that allows interacting with pages and instrumenting them.

diff --git a/docs/api/dock.md b/docs/api/dock.md
@@ -2,7 +2,8 @@
 
 > Control your app in the macOS dock
 
-Process: [Main](../glossary.md#main-process)
+Process: [Main](../glossary.md#main-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 The following example shows how to bounce your icon on the dock.
 

diff --git a/docs/api/download-item.md b/docs/api/download-item.md
@@ -2,7 +2,8 @@
 
 > Control file downloads from remote sources.
 
-Process: [Main](../glossary.md#main-process)
+Process: [Main](../glossary.md#main-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 `DownloadItem` is an [EventEmitter][event-emitter] that represents a download item in Electron.
 It is used in `will-download` event of `Session` class, and allows users to

diff --git a/docs/api/incoming-message.md b/docs/api/incoming-message.md
@@ -2,7 +2,8 @@
 
 > Handle responses to HTTP/HTTPS requests.
 
-Process: [Main](../glossary.md#main-process)
+Process: [Main](../glossary.md#main-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 `IncomingMessage` implements the [Readable Stream](https://nodejs.org/api/stream.html#stream_readable_streams)
 interface and is therefore an [EventEmitter][event-emitter].

diff --git a/docs/api/message-port-main.md b/docs/api/message-port-main.md
@@ -16,7 +16,8 @@ channel messaging.
 
 > Port interface for channel messaging in the main process.
 
-Process: [Main](../glossary.md#main-process)
+Process: [Main](../glossary.md#main-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 ### Instance Methods
 

diff --git a/docs/api/native-image.md b/docs/api/native-image.md
@@ -215,7 +215,8 @@ where `SYSTEM_IMAGE_NAME` should be replaced with any value from [this list](htt
 
 > Natively wrap images such as tray, dock, and application icons.
 
-Process: [Main](../glossary.md#main-process), [Renderer](../glossary.md#renderer-process)
+Process: [Main](../glossary.md#main-process), [Renderer](../glossary.md#renderer-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 ### Instance Methods
 

diff --git a/docs/api/service-workers.md b/docs/api/service-workers.md
@@ -2,7 +2,8 @@
 
 > Query and receive events from a sessions active service workers.
 
-Process: [Main](../glossary.md#main-process)
+Process: [Main](../glossary.md#main-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 Instances of the `ServiceWorkers` class are accessed by using `serviceWorkers` property of
 a `Session`.

diff --git a/docs/api/session.md b/docs/api/session.md
@@ -54,7 +54,8 @@ A `Session` object, the default session object of the app.
 
 > Get and set properties of a session.
 
-Process: [Main](../glossary.md#main-process)
+Process: [Main](../glossary.md#main-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 You can create a `Session` object in the `session` module:
 

diff --git a/docs/api/touch-bar-button.md b/docs/api/touch-bar-button.md
@@ -2,7 +2,8 @@
 
 > Create a button in the touch bar for native macOS applications
 
-Process: [Main](../glossary.md#main-process)
+Process: [Main](../glossary.md#main-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 ### `new TouchBarButton(options)`
 

diff --git a/docs/api/touch-bar-color-picker.md b/docs/api/touch-bar-color-picker.md
@@ -2,7 +2,8 @@
 
 > Create a color picker in the touch bar for native macOS applications
 
-Process: [Main](../glossary.md#main-process)
+Process: [Main](../glossary.md#main-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 ### `new TouchBarColorPicker(options)`
 

diff --git a/docs/api/touch-bar-group.md b/docs/api/touch-bar-group.md
@@ -2,7 +2,8 @@
 
 > Create a group in the touch bar for native macOS applications
 
-Process: [Main](../glossary.md#main-process)
+Process: [Main](../glossary.md#main-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 ### `new TouchBarGroup(options)`
 

diff --git a/docs/api/touch-bar-label.md b/docs/api/touch-bar-label.md
@@ -2,7 +2,8 @@
 
 > Create a label in the touch bar for native macOS applications
 
-Process: [Main](../glossary.md#main-process)
+Process: [Main](../glossary.md#main-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 ### `new TouchBarLabel(options)`
 

diff --git a/docs/api/touch-bar-other-items-proxy.md b/docs/api/touch-bar-other-items-proxy.md
@@ -7,6 +7,7 @@
 >
 > Note: Only one instance of this class can be added per TouchBar.
 
-Process: [Main](../glossary.md#main-process)
+Process: [Main](../glossary.md#main-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 ### `new TouchBarOtherItemsProxy()`
diff --git a/docs/api/touch-bar-popover.md b/docs/api/touch-bar-popover.md
@@ -2,7 +2,8 @@
 
 > Create a popover in the touch bar for native macOS applications
 
-Process: [Main](../glossary.md#main-process)
+Process: [Main](../glossary.md#main-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 ### `new TouchBarPopover(options)`
 

diff --git a/docs/api/touch-bar-scrubber.md b/docs/api/touch-bar-scrubber.md
@@ -2,7 +2,8 @@
 
 > Create a scrubber (a scrollable selector)
 
-Process: [Main](../glossary.md#main-process)
+Process: [Main](../glossary.md#main-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 ### `new TouchBarScrubber(options)`
 

diff --git a/docs/api/touch-bar-segmented-control.md b/docs/api/touch-bar-segmented-control.md
@@ -2,7 +2,8 @@
 
 > Create a segmented control (a button group) where one button has a selected state
 
-Process: [Main](../glossary.md#main-process)
+Process: [Main](../glossary.md#main-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 ### `new TouchBarSegmentedControl(options)`
 

diff --git a/docs/api/touch-bar-slider.md b/docs/api/touch-bar-slider.md
@@ -2,7 +2,8 @@
 
 > Create a slider in the touch bar for native macOS applications
 
-Process: [Main](../glossary.md#main-process)
+Process: [Main](../glossary.md#main-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 ### `new TouchBarSlider(options)`
 

diff --git a/docs/api/touch-bar-spacer.md b/docs/api/touch-bar-spacer.md
@@ -2,7 +2,8 @@
 
 > Create a spacer between two items in the touch bar for native macOS applications
 
-Process: [Main](../glossary.md#main-process)
+Process: [Main](../glossary.md#main-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 ### `new TouchBarSpacer(options)`
 

diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md
@@ -49,7 +49,8 @@ Returns `WebContents` | undefined - A WebContents instance with the given ID, or
 
 > Render and control the contents of a BrowserWindow instance.
 
-Process: [Main](../glossary.md#main-process)
+Process: [Main](../glossary.md#main-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 ### Instance Events
 

diff --git a/docs/api/web-frame-main.md b/docs/api/web-frame-main.md
@@ -68,7 +68,8 @@ or `undefined` if there is no WebFrameMain associated with the given IDs.
 
 ## Class: WebFrameMain
 
-Process: [Main](../glossary.md#main-process)
+Process: [Main](../glossary.md#main-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 ### Instance Methods
 

diff --git a/docs/api/web-request.md b/docs/api/web-request.md
@@ -2,7 +2,8 @@
 
 > Intercept and modify the contents of a request at various stages of its lifetime.
 
-Process: [Main](../glossary.md#main-process)
+Process: [Main](../glossary.md#main-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 Instances of the `WebRequest` class are accessed by using the `webRequest`
 property of a `Session`.

diff --git a/docs/api/webview-tag.md b/docs/api/webview-tag.md
@@ -18,7 +18,8 @@ more information see the [BrowserWindow constructor docs](browser-window.md).
 
 > Display external web content in an isolated frame and process.
 
-Process: [Renderer](../glossary.md#renderer-process)
+Process: [Renderer](../glossary.md#renderer-process)<br />
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
 Use the `webview` tag to embed 'guest' content (such as web pages) in your
 Electron app. The guest content is contained within the `webview` container.

diff --git 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.11.0",
-    "@electron/typescript-definitions": "^8.9.0",
+    "@electron/docs-parser": "^0.12.1",
+    "@electron/typescript-definitions": "^8.9.4",
     "@octokit/auth-app": "^2.10.0",
     "@octokit/rest": "^18.0.3",
     "@primer/octicons": "^10.0.0",
@@ -143,4 +143,4 @@
       "node script/gen-hunspell-filenames.js"
     ]
   }
-}
+}
diff --git a/spec-main/api-ipc-spec.ts b/spec-main/api-ipc-spec.ts
@@ -449,7 +449,7 @@ describe('ipc module', () => {
       });
     });
 
-    const generateTests = (title: string, postMessage: (contents: WebContents) => typeof WebContents.prototype.postMessage) => {
+    const generateTests = (title: string, postMessage: (contents: WebContents) => WebContents['postMessage']) => {
       describe(title, () => {
         it('sends a message', async () => {
           const w = new BrowserWindow({ show: false, webPreferences: { nodeIntegration: true, contextIsolation: false } });

diff --git a/yarn.lock b/yarn.lock
@@ -18,10 +18,10 @@
     esutils "^2.0.2"
     js-tokens "^4.0.0"
 
-"@electron/docs-parser@^0.11.0":
-  version "0.11.0"
-  resolved "https://registry.yarnpkg.com/@electron/docs-parser/-/docs-parser-0.11.0.tgz#182a9732d2fc7b40e3f506d3ab1a06270cdae6e4"
-  integrity sha512-i+OSWXXchoKVorR6cANqPKYJ1ccLAp+YCPTB+IJVWZ+Xtp6V2VXqLsjoy4mD32ss4CdX/6MLX62pb2sjGmmR6w==
+"@electron/docs-parser@^0.12.1":
+  version "0.12.1"
+  resolved "https://registry.yarnpkg.com/@electron/docs-parser/-/docs-parser-0.12.1.tgz#254c324b5953c67cdcce0a8902736778a1788742"
+  integrity sha512-E9/GjNVlFzBM2MNOoLjiKSE0xAMM3KsxvzMKmMeORY7aDbalObFm23XCh8DC8Jn/hfh6BzgVPF3OZO9hKvs5nw==
   dependencies:
     "@types/markdown-it" "^10.0.0"
     chai "^4.2.0"
@@ -33,10 +33,10 @@
     ora "^4.0.3"
     pretty-ms "^5.1.0"
 
-"@electron/typescript-definitions@^8.9.0":
-  version "8.9.0"
-  resolved "https://registry.yarnpkg.com/@electron/typescript-definitions/-/typescript-definitions-8.9.0.tgz#4a446ef875b55f6d3736df2a33bb19257b8146aa"
-  integrity sha512-26ze33/Ip2ivpCMHGRMLR+Dcm7DLNzPJL0iLJNonqPu2ikqnwJce1d2vkTDBBLzAiqUV3litVNTpnNS2Zg42MA==
+"@electron/typescript-definitions@^8.9.4":
+  version "8.9.4"
+  resolved "https://registry.yarnpkg.com/@electron/typescript-definitions/-/typescript-definitions-8.9.4.tgz#ec5c47aad3d45f2da2c40e22536720a9de64c2aa"
+  integrity sha512-KL3ohLe4D5lhJagBEj1Jpoh4BBiJMoCMlc6RSLPT+DaP0odgjEK+Ky6whRDW1cDDpgaSfMisdbN+CdOx3Y7JOg==
   dependencies:
     "@types/node" "^11.13.7"
     chalk "^2.4.2"