fix(types): fix return types where JSDoc and api.md disagree (#3512)

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]<?[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`.
 
 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]<?[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`.
 
 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"`.
 

lib/Browser.js

@@ -195,6 +195,7 @@ class Browser extends EventEmitter {
   /**
    * @param {function(!Target):boolean} predicate
    * @param {{timeout?: number}=} options
+   * @return {!Promise<!Target>}
    */
   async waitForTarget(predicate, options = {}) {
     const {
@@ -298,6 +299,7 @@ class BrowserContext extends EventEmitter {
   /**
    * @param {function(!Target):boolean} predicate
    * @param {{timeout?: number}=} options
+   * @return {!Promise<!Target>}
    */
   waitForTarget(predicate, options) {
     return this._browser.waitForTarget(target => target.browserContext() === this && predicate(target), options);

lib/BrowserFetcher.js

@@ -161,7 +161,6 @@ class BrowserFetcher {
 
   /**
    * @param {string} revision
-   * @return {!Promise}
    */
   async remove(revision) {
     const folderPath = this._getFolderPath(revision);

lib/ExecutionContext.js

@@ -215,7 +215,7 @@ class JSHandle {
   }
 
   /**
-   * @return {!Promise<Map<string, !JSHandle>>}
+   * @return {!Promise<!Map<string, !JSHandle>>}
    */
   async getProperties() {
     const response = await this._client.send('Runtime.getProperties', {
@@ -404,12 +404,11 @@ class ElementHandle extends JSHandle {
 
   /**
    * @param {!Array<string>} 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<Object>}
+   * @returns {!Promise<string|!Buffer>}
    */
   async screenshot(options = {}) {
     let needsViewportReset = false;

lib/FrameManager.js

@@ -777,7 +777,7 @@ class Frame {
    * @param {(string|number|Function)} selectorOrFunctionOrTimeout
    * @param {!Object=} options
    * @param {!Array<*>} args
-   * @return {!Promise}
+   * @return {!Promise<!Puppeteer.JSHandle>}
    */
   waitFor(selectorOrFunctionOrTimeout, options = {}, ...args) {
     const xPathPattern = '//';
@@ -798,7 +798,7 @@ class Frame {
   /**
    * @param {string} selector
    * @param {!Object=} options
-   * @return {!Promise}
+   * @return {!Promise<!Puppeteer.ElementHandle>}
    */
   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<!Puppeteer.ElementHandle>}
    */
   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<!Puppeteer.JSHandle>}
    */
   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<!Puppeteer.ElementHandle>}
    */
   _waitForSelectorOrXPath(selectorOrXPath, isXPath, options = {}) {
     const waitForVisible = !!options.visible;

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;

lib/Page.js

@@ -565,7 +565,7 @@ class Page extends EventEmitter {
   }
 
   /**
-   * @return {!Promise<String>}
+   * @return {!Promise<string>}
    */
   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
+   * @param {boolean} enabled
-   * @returns {!Promise}
    */
   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<!Puppeteer.JSHandle>}
    */
   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<!Puppeteer.ElementHandle>}
    */
   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<!Puppeteer.ElementHandle>}
    */
   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<!Puppeteer.JSHandle>}
    */
   waitForFunction(pageFunction, options = {}, ...args) {
     return this.mainFrame().waitForFunction(pageFunction, options, ...args);

lib/Tracing.js

@@ -55,6 +55,9 @@ class Tracing {
     });
   }
 
+  /**
+   * @return {!Promise<!Buffer>}
+   */
   async stop() {
     let fulfill;
     const contentPromise = new Promise(x => fulfill = x);