chore(types): generate our own d.ts file from api.md (#3744)

Generate `//index.d.ts` file with precise typescript definitions for all of the
Puppeteer API.

.appveyor.yml

@@ -11,7 +11,8 @@ install:
   - if "%nodejs_version%" == "8.11.3" (
       npm run lint &&
       npm run coverage  &&
-      npm run test-doclint
+      npm run test-doclint &&
+      npm run test-types
     ) else (
       npm run unit-node6
     )

.cirrus.yml

@@ -20,6 +20,7 @@ task:
   lint_script: npm run lint
   coverage_script: npm run coverage
   test_doclint_script: npm run test-doclint
+  test_types_script: npm run test-types
 
 task:
   osx_instance:
@@ -34,3 +35,4 @@ task:
   lint_script: npm run lint
   coverage_script: npm run coverage
   test_doclint_script: npm run test-doclint
+  test_types_script: npm run test-types

.gitignore

@@ -12,3 +12,4 @@ yarn.lock
 /node6
 /lib/protocol.d.ts
 /utils/browser/puppeteer-web.js
+/index.d.ts

.travis.yml

@@ -19,6 +19,7 @@ script:
   - 'if [ "$NODE8" = "true" ]; then npm run lint; fi'
   - 'if [ "$NODE8" = "true" ]; then npm run coverage; fi'
   - 'if [ "$NODE8" = "true" ]; then npm run test-doclint; fi'
+  - 'if [ "$NODE8" = "true" ]; then npm run test-types; fi'
   - 'if [ "$NODE8" = "true" ]; then npm run bundle; fi'
   - 'if [ "$NODE8" = "true" ]; then npm run unit-bundle; fi'
   - 'if [ "$NODE6" = "true" ]; then npm run unit-node6; fi'

docs/api.md

@@ -565,7 +565,7 @@ The method initiates a GET request to download the revision from the host.
 - returns: <[Promise]<[Array]<[string]>>> A list of all revisions available locally on disk.
 
 #### browserFetcher.platform()
-- returns: <[string]> Returns one of `mac`, `linux`, `win32` or `win64`.
+- returns: <[string]> One of `mac`, `linux`, `win32` or `win64`.
 
 #### browserFetcher.remove(revision)
 - `revision` <[string]> a revision to remove. The method will throw if the revision has not been downloaded.
@@ -582,7 +582,7 @@ The method initiates a GET request to download the revision from the host.
 
 ### class: Browser
 
-* extends: [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter)
+* extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
 
 A Browser is created when Puppeteer connects to a Chromium instance, either through [`puppeteer.launch`](#puppeteerlaunchoptions) or [`puppeteer.connect`](#puppeteerconnectoptions).
 
@@ -734,7 +734,7 @@ You can find the `webSocketDebuggerUrl` from `http://${host}:${port}/json/versio
 
 ### class: BrowserContext
 
-* extends: [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter)
+* extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
 
 BrowserContexts provide a way to operate multiple independent browser sessions. When a browser is launched, it has
 a single BrowserContext used by default. The method `browser.newPage()` creates a page in the default browser context.
@@ -864,7 +864,7 @@ const newWindowTarget = await browserContext.waitForTarget(target => target.url(
 
 ### class: Page
 
-* extends: [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter)
+* extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
 
 Page provides methods to interact with a single tab or [extension background page](https://developer.chrome.com/extensions/background_pages) in Chromium. One [Browser] instance might have multiple [Page] instances.
 
@@ -1035,7 +1035,7 @@ Shortcut for [page.mainFrame().$$(selector)](#frameselector-1).
 
 #### page.$$eval(selector, pageFunction[, ...args])
 - `selector` <[string]> A [selector] to query page for
-- `pageFunction` <[function]> Function to be evaluated in browser context
+- `pageFunction` <[function]\([Array]<[Element]>\)> Function to be evaluated in browser context
 - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
 - returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
 
@@ -1050,7 +1050,7 @@ const divsCounts = await page.$$eval('div', divs => divs.length);
 
 #### page.$eval(selector, pageFunction[, ...args])
 - `selector` <[string]> A [selector] to query page for
-- `pageFunction` <[function]> Function to be evaluated in browser context
+- `pageFunction` <[function]\([Element]\)> Function to be evaluated in browser context
 - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
 - returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
 
@@ -1464,7 +1464,7 @@ Indicates that the page has been closed.
 - returns: <[Keyboard]>
 
 #### page.mainFrame()
-- returns: <[Frame]> returns page's main frame.
+- returns: <[Frame]> The page's main frame.
 
 Page is guaranteed to have a main frame which persists during navigations.
 
@@ -1609,7 +1609,7 @@ Shortcut for [page.mainFrame().executionContext().queryObjects(prototypeHandle)]
 #### page.select(selector, ...values)
 - `selector` <[string]> A [selector] to query page for
 - `...values` <...[string]> Values of options to select. If the `<select>` has the `multiple` attribute, all values are considered, otherwise only the first one is taken into account.
-- returns: <[Promise]<[Array]<[string]>>> Returns an array of option values that have been successfully selected.
+- returns: <[Promise]<[Array]<[string]>>> An array of option values that have been successfully selected.
 
 Triggers a `change` and `input` event once all the provided options have been selected.
 If there's no `<select>` element matching `selector`, the method throws an error.
@@ -1767,7 +1767,7 @@ Shortcut for [page.mainFrame().tap(selector)](#frametapselector).
 - returns: <[Target]> a target this page was created from.
 
 #### page.title()
-- returns: <[Promise]<[string]>> Returns page's title.
+- returns: <[Promise]<[string]>> The page's title.
 
 Shortcut for [page.mainFrame().title()](#frametitle).
 
@@ -2042,7 +2042,7 @@ Most of the accessibility tree gets filtered out when converting from Blink AX T
 #### accessibility.snapshot([options])
 - `options` <[Object]>
   - `interestingOnly` <[boolean]> Prune uninteresting nodes from the tree. Defaults to `true`.
-- returns: <[Promise]<[Object]>> Returns an [AXNode] object with the following properties:
+- returns: <[Promise]<[Object]>> An [AXNode] object with the following properties:
   - `role` <[string]> The [role](https://www.w3.org/TR/wai-aria/#usage_intro).
   - `name` <[string]> A human readable name for the node.
   - `value` <[string]|[number]> The current value of the node.
@@ -2382,7 +2382,7 @@ The method runs `document.querySelectorAll` within the frame. If no elements mat
 
 #### frame.$$eval(selector, pageFunction[, ...args])
 - `selector` <[string]> A [selector] to query frame for
-- `pageFunction` <[function]> Function to be evaluated in browser context
+- `pageFunction` <[function]\([Array]<[Element]>\)> Function to be evaluated in browser context
 - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
 - returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
 
@@ -2397,7 +2397,7 @@ const divsCounts = await frame.$$eval('div', divs => divs.length);
 
 #### frame.$eval(selector, pageFunction[, ...args])
 - `selector` <[string]> A [selector] to query frame for
-- `pageFunction` <[function]> Function to be evaluated in browser context
+- `pageFunction` <[function]\([Element]\)> Function to be evaluated in browser context
 - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
 - returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
 
@@ -2580,12 +2580,12 @@ If the name is empty, returns the id attribute instead.
 > **NOTE** This value is calculated once when the frame is created, and will not update if the attribute is changed later.
 
 #### frame.parentFrame()
-- returns: <?[Frame]> Returns parent frame, if any. Detached frames and main frames return `null`.
+- returns: <?[Frame]> Parent frame, if any. Detached frames and main frames return `null`.
 
 #### frame.select(selector, ...values)
 - `selector` <[string]> A [selector] to query frame for
 - `...values` <...[string]> Values of options to select. If the `<select>` has the `multiple` attribute, all values are considered, otherwise only the first one is taken into account.
-- returns: <[Promise]<[Array]<[string]>>> Returns an array of option values that have been successfully selected.
+- returns: <[Promise]<[Array]<[string]>>> An array of option values that have been successfully selected.
 
 Triggers a `change` and `input` event once all the provided options have been selected.
 If there's no `<select>` element matching `selector`, the method throws an error.
@@ -2614,7 +2614,7 @@ This method fetches an element with `selector`, scrolls it into view if needed,
 If there's no element matching `selector`, the method throws an error.
 
 #### frame.title()
-- returns: <[Promise]<[string]>> Returns page's title.
+- returns: <[Promise]<[string]>> The page's title.
 
 #### frame.type(selector, text[, options])
 - `selector` <[string]> A [selector] of an element to type into. If there are multiple elements satisfying the selector, the first will be used.
@@ -2925,8 +2925,7 @@ function, it **will not be called**.
 > **NOTE** The method will return an empty JSON object if the referenced object is not stringifiable. It will throw an error if the object has circular references.
 
 ### class: ElementHandle
-
-> **NOTE** Class [ElementHandle] extends [JSHandle].
+* extends: [JSHandle]
 
 ElementHandle represents an in-page DOM element. ElementHandles can be created with the [page.$](#pageselector) method.
 
@@ -2960,7 +2959,7 @@ The method runs `element.querySelectorAll` within the page. If no elements match
 
 #### elementHandle.$$eval(selector, pageFunction[, ...args])
 - `selector` <[string]> A [selector] to query page for
-- `pageFunction` <[function]> Function to be evaluated in browser context
+- `pageFunction` <[function]\([Array]<[Element]>\)> Function to be evaluated in browser context
 - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
 - returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
 
@@ -2982,7 +2981,7 @@ expect(await feedHandle.$$eval('.tweet', nodes => nodes.map(n => n.innerText))).
 
 #### elementHandle.$eval(selector, pageFunction[, ...args])
 - `selector` <[string]> A [selector] to query page for
-- `pageFunction` <[function]> Function to be evaluated in browser context
+- `pageFunction` <[function]\([Element]\)> Function to be evaluated in browser context
 - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
 - returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
 
@@ -3432,7 +3431,7 @@ Identifies what kind of target this is. Can be `"page"`, [`"background_page"`](h
 
 ### class: CDPSession
 
-* extends: [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter)
+* extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
 
 The `CDPSession` instances are used to talk raw Chrome Devtools Protocol:
 - protocol methods can be called with `session.send` method.

lib/Page.js

@@ -46,7 +46,6 @@ class Page extends EventEmitter {
     await client.send('Page.enable');
     const {frameTree} = await client.send('Page.getFrameTree');
     const page = new Page(client, target, frameTree, ignoreHTTPSErrors, screenshotTaskQueue);
-
     await Promise.all([
       client.send('Target.setAutoAttach', {autoAttach: true, waitForDebuggerOnStart: false, flatten: true}),
       client.send('Page.setLifecycleEventsEnabled', { enabled: true }),

package.json

@@ -14,18 +14,19 @@
     "unit": "node test/test.js",
     "debug-unit": "node --inspect-brk test/test.js",
     "test-doclint": "node utils/doclint/check_public_api/test/test.js && node utils/doclint/preprocessor/test.js",
-    "test": "npm run lint --silent && npm run coverage && npm run test-doclint && npm run test-node6-transformer",
+    "test": "npm run lint --silent && npm run coverage && npm run test-doclint && npm run test-node6-transformer && npm run test-types",
     "install": "node install.js",
     "lint": "([ \"$CI\" = true ] && eslint --quiet -f codeframe . || eslint .) && npm run tsc && npm run doc",
     "doc": "node utils/doclint/cli.js",
     "coverage": "cross-env COVERAGE=true npm run unit",
     "test-node6-transformer": "node utils/node6-transform/test/test.js",
-    "build": "node utils/node6-transform/index.js",
+    "build": "node utils/node6-transform/index.js && node utils/doclint/generate_types",
     "unit-node6": "node node6/test/test.js",
     "tsc": "tsc -p .",
     "prepublishOnly": "npm run build",
     "apply-next-version": "node utils/apply_next_version.js",
     "bundle": "npx browserify -r ./index.js:puppeteer -o utils/browser/puppeteer-web.js",
+    "test-types": "node utils/doclint/generate_types && npx -p typescript@2.1 tsc -p utils/doclint/generate_types/test/",
     "unit-bundle": "node utils/browser/test.js"
   },
   "author": "The Chromium Authors",

utils/doclint/check_public_api/Documentation.js

@@ -31,8 +31,10 @@ Documentation.Class = class {
   /**
    * @param {string} name
    * @param {!Array<!Documentation.Member>} membersArray
+   * @param {?string=} extendsName
+   * @param {string=} comment
    */
-  constructor(name, membersArray) {
+  constructor(name, membersArray, extendsName = null, comment = '') {
     this.name = name;
     this.membersArray = membersArray;
     /** @type {!Map<string, !Documentation.Member>} */
@@ -43,6 +45,8 @@ Documentation.Class = class {
     this.methods = new Map();
     /** @type {!Map<string, !Documentation.Member>} */
     this.events = new Map();
+    this.comment = comment;
+    this.extends = extendsName;
     for (const member of membersArray) {
       this.members.set(member.name, member);
       if (member.kind === 'method')
@@ -59,14 +63,17 @@ Documentation.Member = class {
   /**
    * @param {string} kind
    * @param {string} name
-   * @param {!Documentation.Type} type
+   * @param {?Documentation.Type} type
    * @param {!Array<!Documentation.Member>} argsArray
    */
-  constructor(kind, name, type, argsArray) {
+  constructor(kind, name, type, argsArray, comment = '', returnComment = '', required = true) {
     this.kind = kind;
     this.name = name;
     this.type = type;
+    this.comment = comment;
+    this.returnComment = returnComment;
     this.argsArray = argsArray;
+    this.required = required;
     /** @type {!Map<string, !Documentation.Member>} */
     this.args = new Map();
     for (const arg of argsArray)
@@ -79,25 +86,29 @@ Documentation.Member = class {
    * @param {?Documentation.Type} returnType
    * @return {!Documentation.Member}
    */
-  static createMethod(name, argsArray, returnType) {
-    return new Documentation.Member('method', name, returnType, argsArray,);
+  static createMethod(name, argsArray, returnType, returnComment, comment) {
+    return new Documentation.Member('method', name, returnType, argsArray, comment, returnComment);
   }
 
   /**
    * @param {string} name
-   * @param {!Documentation.Type}
+   * @param {!Documentation.Type} type
+   * @param {string=} comment
+   * @param {boolean=} required
    * @return {!Documentation.Member}
    */
-  static createProperty(name, type) {
-    return new Documentation.Member('property', name, type, []);
+  static createProperty(name, type, comment, required) {
+    return new Documentation.Member('property', name, type, [], comment, undefined, required);
   }
 
   /**
    * @param {string} name
+   * @param {?Documentation.Type=} type
+   * @param {string=} comment
    * @return {!Documentation.Member}
    */
-  static createEvent(name) {
-    return new Documentation.Member('event', name, null, []);
+  static createEvent(name, type = null, comment) {
+    return new Documentation.Member('event', name, type, [], comment);
   }
 };