From 79ec7a3fe5630cb0ee186c8db6807bd0ff2e0f51 Mon Sep 17 00:00:00 2001 From: Joel Einbinder Date: Wed, 7 Nov 2018 22:48:43 -0800 Subject: [PATCH] fix(types): fix return types where JSDoc and api.md disagree (#3512) --- docs/api.md | 18 +++++++++--------- lib/Browser.js | 2 ++ lib/BrowserFetcher.js | 1 - lib/ExecutionContext.js | 7 +++---- lib/FrameManager.js | 10 +++++----- lib/Input.js | 1 - lib/Page.js | 15 +++++++-------- lib/Tracing.js | 3 +++ 8 files changed, 29 insertions(+), 28 deletions(-) diff --git a/docs/api.md b/docs/api.md index 5da62315f2a..9ec25a2effe 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1133,7 +1133,7 @@ By default, `page.close()` **does not** run beforeunload handlers. > and should be handled manually via page's ['dialog'](#event-dialog) event. #### page.content() -- returns: <[Promise]<[String]>> +- returns: <[Promise]<[string]>> Gets the full HTML contents of the page, including the doctype. @@ -1571,7 +1571,7 @@ Shortcut for [page.mainFrame().executionContext().queryObjects(prototypeHandle)] - `height` <[number]> height of clipping area - `omitBackground` <[boolean]> Hides default white background and allows capturing screenshots with transparency. Defaults to `false`. - `encoding` <[string]> The encoding of the image, can be either `base64` or `binary`. Defaults to `binary`. -- returns: <[Promise]<[Buffer|String]>> Promise which resolves to buffer or a base64 string (depending on the value of `encoding`) with captured screenshot. +- returns: <[Promise]<[string]|[Buffer]>> Promise which resolves to buffer or a base64 string (depending on the value of `encoding`) with captured screenshot. > **NOTE** Screenshots take at least 1/6 second on OS X. See https://crbug.com/741689 for discussion. @@ -1645,7 +1645,7 @@ The extra HTTP headers will be sent with every request the page initiates. > **NOTE** page.setExtraHTTPHeaders does not guarantee the order of headers in the outgoing requests. #### page.setGeolocation(options) -- `options` +- `options` <[Object]> - `latitude` <[number]> Latitude between -90 and 90. - `longitude` <[number]> Longitude between -180 and 180. - `accuracy` <[number]> Optional non-negative accuracy value. @@ -1842,7 +1842,7 @@ Shortcut for [page.mainFrame().waitForFunction(pageFunction[, options[, ...args] - `domcontentloaded` - consider navigation to be finished when the `DOMContentLoaded` event is fired. - `networkidle0` - consider navigation to be finished when there are no more than 0 network connections for at least `500` ms. - `networkidle2` - consider navigation to be finished when there are no more than 2 network connections for at least `500` ms. -- returns: <[Promise]<[?Response]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. In case of navigation to a different anchor or navigation due to History API usage, the navigation will resolve with `null`. +- returns: <[Promise]> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. In case of navigation to a different anchor or navigation due to History API usage, the navigation will resolve with `null`. This resolves when the page navigates to a new URL or reloads. It is useful for when you run code which will indirectly cause the page to navigate. Consider this example: @@ -2417,7 +2417,7 @@ const [response] = await Promise.all([ ``` #### frame.content() -- returns: <[Promise]<[String]>> +- returns: <[Promise]<[string]>> Gets the full HTML contents of the frame, including the doctype. @@ -2653,7 +2653,7 @@ await page.waitForFunction(selector => !!document.querySelector(selector), {}, s - `domcontentloaded` - consider navigation to be finished when the `DOMContentLoaded` event is fired. - `networkidle0` - consider navigation to be finished when there are no more than 0 network connections for at least `500` ms. - `networkidle2` - consider navigation to be finished when there are no more than 2 network connections for at least `500` ms. -- returns: <[Promise]<[?Response]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. In case of navigation to a different anchor or navigation due to History API usage, the navigation will resolve with `null`. +- returns: <[Promise]> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. In case of navigation to a different anchor or navigation due to History API usage, the navigation will resolve with `null`. This resolves when the frame navigates to a new URL. It is useful for when you run code which will indirectly cause the frame to navigate. Consider this example: @@ -2800,7 +2800,7 @@ await resultHandle.dispose(); #### executionContext.queryObjects(prototypeHandle) - `prototypeHandle` <[JSHandle]> A handle to the object prototype. -- returns: <[JSHandle]> A handle to an array of objects with this prototype +- returns: <[Promise]<[JSHandle]>> A handle to an array of objects with this prototype The method iterates the JavaScript heap and finds all the objects with the given prototype. @@ -3055,7 +3055,7 @@ If `key` is a single character and no modifier keys besides `Shift` are being he #### elementHandle.screenshot([options]) - `options` <[Object]> Same options as in [page.screenshot](#pagescreenshotoptions). -- returns: <[Promise]<[Buffer]>> Promise which resolves to buffer with captured screenshot. +- returns: <[Promise]<[string]|[Buffer]>> Promise which resolves to buffer with captured screenshot. This method scrolls element into view if needed, and then uses [page.screenshot](#pagescreenshotoptions) to take a screenshot of the element. If the element is detached from DOM, the method throws an error. @@ -3364,7 +3364,7 @@ Get the target that opened this target. Top-level targets return `null`. If the target is not of type `"page"` or `"background_page"`, returns `null`. #### target.type() -- returns: <[string]> +- returns: <"page"|"background_page"|"service_worker"|"other"|"browser"> Identifies what kind of target this is. Can be `"page"`, [`"background_page"`](https://developer.chrome.com/extensions/background_pages), `"service_worker"`, `"browser"` or `"other"`. diff --git a/lib/Browser.js b/lib/Browser.js index c8df1236ed1..333a465472c 100644 --- a/lib/Browser.js +++ b/lib/Browser.js @@ -195,6 +195,7 @@ class Browser extends EventEmitter { /** * @param {function(!Target):boolean} predicate * @param {{timeout?: number}=} options + * @return {!Promise} */ async waitForTarget(predicate, options = {}) { const { @@ -298,6 +299,7 @@ class BrowserContext extends EventEmitter { /** * @param {function(!Target):boolean} predicate * @param {{timeout?: number}=} options + * @return {!Promise} */ waitForTarget(predicate, options) { return this._browser.waitForTarget(target => target.browserContext() === this && predicate(target), options); diff --git a/lib/BrowserFetcher.js b/lib/BrowserFetcher.js index ecb174b40c0..c5136a0e186 100644 --- a/lib/BrowserFetcher.js +++ b/lib/BrowserFetcher.js @@ -161,7 +161,6 @@ class BrowserFetcher { /** * @param {string} revision - * @return {!Promise} */ async remove(revision) { const folderPath = this._getFolderPath(revision); diff --git a/lib/ExecutionContext.js b/lib/ExecutionContext.js index fd2c7d03bab..ab210dd5a0c 100644 --- a/lib/ExecutionContext.js +++ b/lib/ExecutionContext.js @@ -215,7 +215,7 @@ class JSHandle { } /** - * @return {!Promise>} + * @return {!Promise>} */ async getProperties() { const response = await this._client.send('Runtime.getProperties', { @@ -404,12 +404,11 @@ class ElementHandle extends JSHandle { /** * @param {!Array} filePaths - * @return {!Promise} */ async uploadFile(...filePaths) { const files = filePaths.map(filePath => path.resolve(filePath)); const objectId = this._remoteObject.objectId; - return this._client.send('DOM.setFileInputFiles', { objectId, files }); + await this._client.send('DOM.setFileInputFiles', { objectId, files }); } async tap() { @@ -481,7 +480,7 @@ class ElementHandle extends JSHandle { /** * * @param {!Object=} options - * @returns {!Promise} + * @returns {!Promise} */ async screenshot(options = {}) { let needsViewportReset = false; diff --git a/lib/FrameManager.js b/lib/FrameManager.js index 1868affd902..3660ab9db83 100644 --- a/lib/FrameManager.js +++ b/lib/FrameManager.js @@ -777,7 +777,7 @@ class Frame { * @param {(string|number|Function)} selectorOrFunctionOrTimeout * @param {!Object=} options * @param {!Array<*>} args - * @return {!Promise} + * @return {!Promise} */ waitFor(selectorOrFunctionOrTimeout, options = {}, ...args) { const xPathPattern = '//'; @@ -798,7 +798,7 @@ class Frame { /** * @param {string} selector * @param {!Object=} options - * @return {!Promise} + * @return {!Promise} */ waitForSelector(selector, options = {}) { return this._waitForSelectorOrXPath(selector, false, options); @@ -807,7 +807,7 @@ class Frame { /** * @param {string} xpath * @param {!Object=} options - * @return {!Promise} + * @return {!Promise} */ waitForXPath(xpath, options = {}) { return this._waitForSelectorOrXPath(xpath, true, options); @@ -816,7 +816,7 @@ class Frame { /** * @param {Function|string} pageFunction * @param {!Object=} options - * @return {!Promise} + * @return {!Promise} */ waitForFunction(pageFunction, options = {}, ...args) { const timeout = helper.isNumber(options.timeout) ? options.timeout : 30000; @@ -835,7 +835,7 @@ class Frame { * @param {string} selectorOrXPath * @param {boolean} isXPath * @param {!Object=} options - * @return {!Promise} + * @return {!Promise} */ _waitForSelectorOrXPath(selectorOrXPath, isXPath, options = {}) { const waitForVisible = !!options.visible; diff --git a/lib/Input.js b/lib/Input.js index 53abf676699..b188697e25a 100644 --- a/lib/Input.js +++ b/lib/Input.js @@ -199,7 +199,6 @@ class Mouse { * @param {number} x * @param {number} y * @param {Object=} options - * @return {!Promise} */ async move(x, y, options = {}) { const fromX = this._x, fromY = this._y; diff --git a/lib/Page.js b/lib/Page.js index f06eba2a0e1..be5f984f3e0 100644 --- a/lib/Page.js +++ b/lib/Page.js @@ -565,7 +565,7 @@ class Page extends EventEmitter { } /** - * @return {!Promise} + * @return {!Promise} */ async content() { return await this._frameManager.mainFrame().content(); @@ -679,7 +679,7 @@ class Page extends EventEmitter { * @param {!Object} options */ async emulate(options) { - return Promise.all([ + await Promise.all([ this.setViewport(options.viewport), this.setUserAgent(options.userAgent) ]); @@ -746,8 +746,7 @@ class Page extends EventEmitter { } /** - * @param {Boolean} enabled - * @returns {!Promise} + * @param {boolean} enabled */ async setCacheEnabled(enabled = true) { await this._client.send('Network.setCacheDisabled', {cacheDisabled: !enabled}); @@ -975,7 +974,7 @@ class Page extends EventEmitter { * @param {(string|number|Function)} selectorOrFunctionOrTimeout * @param {!Object=} options * @param {!Array<*>} args - * @return {!Promise} + * @return {!Promise} */ waitFor(selectorOrFunctionOrTimeout, options = {}, ...args) { return this.mainFrame().waitFor(selectorOrFunctionOrTimeout, options, ...args); @@ -984,7 +983,7 @@ class Page extends EventEmitter { /** * @param {string} selector * @param {!Object=} options - * @return {!Promise} + * @return {!Promise} */ waitForSelector(selector, options = {}) { return this.mainFrame().waitForSelector(selector, options); @@ -993,7 +992,7 @@ class Page extends EventEmitter { /** * @param {string} xpath * @param {!Object=} options - * @return {!Promise} + * @return {!Promise} */ waitForXPath(xpath, options = {}) { return this.mainFrame().waitForXPath(xpath, options); @@ -1003,7 +1002,7 @@ class Page extends EventEmitter { * @param {function()} pageFunction * @param {!Object=} options * @param {!Array<*>} args - * @return {!Promise} + * @return {!Promise} */ waitForFunction(pageFunction, options = {}, ...args) { return this.mainFrame().waitForFunction(pageFunction, options, ...args); diff --git a/lib/Tracing.js b/lib/Tracing.js index 51191884653..4af720870f8 100644 --- a/lib/Tracing.js +++ b/lib/Tracing.js @@ -55,6 +55,9 @@ class Tracing { }); } + /** + * @return {!Promise} + */ async stop() { let fulfill; const contentPromise = new Promise(x => fulfill = x);