chore: Use Typescript to lint JSDoc annotations (#986)

This patch starts using typescript to lint JSDoc annotations.

Note: this uses typescript's bleeding edge. We should migrate to stable once
it has all the necessary bugfixes.

References #65.

lib/Browser.js

@@ -20,9 +20,9 @@ const EventEmitter = require('events');
 
 class Browser extends EventEmitter {
   /**
-   * @param {!Connection} connection
+   * @param {!Puppeteer.Connection} connection
    * @param {!Object=} options
-   * @param {function():Promise=} closeCallback
+   * @param {(function():Promise)=} closeCallback
    */
   constructor(connection, options = {}, closeCallback) {
     super();
@@ -63,7 +63,6 @@ class Browser extends EventEmitter {
   }
 }
 
-module.exports = Browser;
 helper.tracePublicAPI(Browser);
 
 class TaskQueue {
@@ -81,3 +80,4 @@ class TaskQueue {
     return result;
   }
 }
+module.exports = { Browser, TaskQueue };

lib/Connection.js

@@ -173,7 +173,7 @@ class Session extends EventEmitter {
       if (!this._callbacks.has(id))
         return;
       const callback = this._callbacks.get(id);
-      this._callbacks.delete(object.id);
+      this._callbacks.delete(id);
       callback.reject(e);
     });
     return new Promise((resolve, reject) => {
@@ -212,4 +212,4 @@ class Session extends EventEmitter {
   }
 }
 
-module.exports = Connection;
+module.exports = {Connection, Session};

lib/Dialog.js

@@ -18,8 +18,8 @@ const {helper} = require('./helper');
 
 class Dialog {
   /**
-   * @param {!Session} client
-   * @param {!Dialog.Type} type
+   * @param {!Puppeteer.Session} client
+   * @param {string} type
    * @param {string} message
    * @param {(string|undefined)} defaultValue
    */

lib/ElementHandle.js

@@ -19,10 +19,10 @@ const {helper} = require('./helper');
 
 class ElementHandle extends JSHandle {
   /**
-   * @param {!ExecutionContext} context
-   * @param {!Session} client
+   * @param {!Puppeteer.ExecutionContext} context
+   * @param {!Puppeteer.Session} client
    * @param {!Object} remoteObject
-   * @param {!Page} page
+   * @param {!Puppeteer.Page} page
    */
   constructor(context, client, remoteObject, page) {
     super(context, client, remoteObject);
@@ -47,7 +47,7 @@ class ElementHandle extends JSHandle {
     const error = await this.executionContext().evaluate(element => {
       if (!element.ownerDocument.contains(element))
         return 'Node is detached from document';
-      if (element.nodeType !== HTMLElement.ELEMENT_NODE)
+      if (element.nodeType !== Node.ELEMENT_NODE)
         return 'Node is not of type HTMLElement';
       element.scrollIntoViewIfNeeded();
     }, this);

lib/EmulationManager.js

@@ -16,7 +16,7 @@
 
 class EmulationManager {
   /**
-   * @param {!Session} client
+   * @param {!Puppeteer.Session} client
    */
   constructor(client) {
     this._client = client;
@@ -25,7 +25,7 @@ class EmulationManager {
   }
 
   /**
-   * @param {!Page.Viewport} viewport
+   * @param {!EmulationManager.Viewport} viewport
    * @return {Promise<boolean>}
    */
   async emulateViewport(client, viewport) {
@@ -61,6 +61,7 @@ class EmulationManager {
 
     function injectedTouchEventsFunction() {
       const touchEvents = ['ontouchstart', 'ontouchend', 'ontouchmove', 'ontouchcancel'];
+      // @ts-ignore
       const recepients = [window.__proto__, document.__proto__];
       for (let i = 0; i < touchEvents.length; ++i) {
         for (let j = 0; j < recepients.length; ++j) {
@@ -75,4 +76,14 @@ class EmulationManager {
   }
 }
 
+/**
+ * @typedef {Object} EmulationManager.Viewport
+ * @property {number} width
+ * @property {number} height
+ * @property {number=} deviceScaleFactor
+ * @property {boolean=} isMobile
+ * @property {boolean=} isLandscape
+ * @property {boolean=} hasTouch
+ */
+
 module.exports = EmulationManager;

lib/ExecutionContext.js

@@ -18,7 +18,7 @@ const {helper} = require('./helper');
 
 class ExecutionContext {
   /**
-   * @param {!Session} client
+   * @param {!Puppeteer.Session} client
    * @param {string} contextId
    * @param {function(*):!JSHandle} objectHandleFactory
    */
@@ -100,7 +100,7 @@ class ExecutionContext {
 class JSHandle {
   /**
    * @param {!ExecutionContext} context
-   * @param {!Session} client
+   * @param {!Puppeteer.Session} client
    * @param {!Object} remoteObject
    */
   constructor(context, client, remoteObject) {
@@ -134,7 +134,7 @@ class JSHandle {
   }
 
   /**
-   * @return {!Property<Map<string, !ObjectHandle>>}
+   * @return {!Promise<Map<string, !JSHandle>>}
    */
   async getProperties() {
     const response = await this._client.send('Runtime.getProperties', {
@@ -162,7 +162,7 @@ class JSHandle {
   }
 
   /**
-   * @return {?ElementHandle}
+   * @return {?Puppeteer.ElementHandle}
    */
   asElement() {
     return null;

lib/FrameManager.js

@@ -22,8 +22,8 @@ const ElementHandle = require('./ElementHandle');
 
 class FrameManager extends EventEmitter {
   /**
-   * @param {!Session} client
-   * @param {!Page} page
+   * @param {!Puppeteer.Session} client
+   * @param {!Puppeteer.Page} page
    */
   constructor(client, page) {
     super();
@@ -87,7 +87,7 @@ class FrameManager extends EventEmitter {
     if (isMainFrame) {
       if (frame) {
         // Update frame id to retain frame identity on cross-process navigation.
-        this._frames.delete(frame._id, frame);
+        this._frames.delete(frame._id);
         frame._id = framePayload.id;
       } else {
         // Initial main frame navigation.
@@ -154,7 +154,6 @@ class FrameManager extends EventEmitter {
   }
 
   /**
-   * @param {!Frame} frame
    * @return {boolean}
    */
   isMainFrameLoadingFailed() {
@@ -174,7 +173,7 @@ FrameManager.Events = {
  */
 class Frame {
   /**
-   * @param {!Session} client
+   * @param {!Puppeteer.Session} client
    * @param {?Frame} parentFrame
    * @param {string} frameId
    */
@@ -202,9 +201,9 @@ class Frame {
   }
 
   /**
-   * @param {function()|string} pageFunction
+   * @param {Function|string} pageFunction
    * @param {!Array<*>} args
-   * @return {!Promise<(!Object|undefined)>}
+   * @return {!Promise<*>}
    */
   async evaluate(pageFunction, ...args) {
     return this._context.evaluate(pageFunction, ...args);
@@ -225,7 +224,7 @@ class Frame {
 
   /**
    * @param {string} selector
-   * @param {function()|string} pageFunction
+   * @param {Function|string} pageFunction
    * @param {!Array<*>} args
    * @return {!Promise<(!Object|undefined)>}
    */
@@ -344,14 +343,14 @@ class Frame {
   }
 
   /**
-   * @param {(string|number|function())} selectorOrTimeout
+   * @param {(string|number|Function)} selectorOrFunctionOrTimeout
    * @param {!Object=} options
    * @param {!Array<*>} args
    * @return {!Promise}
    */
   waitFor(selectorOrFunctionOrTimeout, options = {}, ...args) {
     if (helper.isString(selectorOrFunctionOrTimeout))
-      return this.waitForSelector(selectorOrFunctionOrTimeout, options);
+      return this.waitForSelector(/** @type {string} */(selectorOrFunctionOrTimeout), options);
     if (helper.isNumber(selectorOrFunctionOrTimeout))
       return new Promise(fulfill => setTimeout(fulfill, selectorOrFunctionOrTimeout));
     if (typeof selectorOrFunctionOrTimeout === 'function')
@@ -387,7 +386,7 @@ class Frame {
   }
 
   /**
-   * @param {function()} pageFunction
+   * @param {Function} pageFunction
    * @param {!Object=} options
    * @return {!Promise}
    */
@@ -429,7 +428,7 @@ class WaitTask {
   /**
    * @param {!Frame} frame
    * @param {string} predicateBody
-   * @param {string} polling
+   * @param {string|number} polling
    * @param {number} timeout
    */
   constructor(frame, predicateBody, polling, timeout) {
@@ -524,7 +523,7 @@ async function waitForPredicatePageFunction(predicateBody, polling, timeout) {
   return !timedOut;
 
   /**
-   * @return {!Promise<!Element>}
+   * @return {!Promise}
    */
   function pollMutation() {
     if (predicate())
@@ -582,4 +581,4 @@ async function waitForPredicatePageFunction(predicateBody, polling, timeout) {
   }
 }
 
-module.exports = FrameManager;
+module.exports = {FrameManager, Frame};

lib/Input.js

@@ -18,7 +18,7 @@ const {helper} = require('./helper');
 
 class Keyboard {
   /**
-   * @param {!Session} client
+   * @param {!Puppeteer.Session} client
    */
   constructor(client) {
     this._client = client;
@@ -28,10 +28,10 @@ class Keyboard {
 
   /**
    * @param {string} key
-   * @param {{text: (string|undefined)}} options
+   * @param {{text: string}=} options
    */
-  async down(key, options = {}) {
-    const text = options.text;
+  async down(key, options = {text: ''}) {
+    const {text} = options;
     const autoRepeat = this._pressedKeys.has(key);
     this._pressedKeys.add(key);
     this._modifiers |= this._modifierBit(key);
@@ -118,7 +118,7 @@ class Keyboard {
 
 class Mouse {
   /**
-   * @param {!Session} client
+   * @param {Puppeteer.Session} client
    * @param {!Keyboard} keyboard
    */
   constructor(client, keyboard) {
@@ -197,7 +197,7 @@ class Mouse {
 
 class Touchscreen {
   /**
-   * @param {Session} client
+   * @param {Puppeteer.Session} client
    * @param {Keyboard} keyboard
    */
   constructor(client, keyboard) {

lib/Launcher.js

@@ -18,11 +18,12 @@ const path = require('path');
 const removeSync = require('rimraf').sync;
 const childProcess = require('child_process');
 const Downloader = require('../utils/ChromiumDownloader');
-const Connection = require('./Connection');
-const Browser = require('./Browser');
+const {Connection} = require('./Connection');
+const {Browser} = require('./Browser');
 const readline = require('readline');
 const fs = require('fs');
 const {helper} = require('./helper');
+// @ts-ignore
 const ChromiumRevision = require('../package.json').puppeteer.chromium_revision;
 
 const CHROME_PROFILE_PATH = path.join(os.tmpdir(), 'puppeteer_dev_profile-');
@@ -178,7 +179,7 @@ class Launcher {
 }
 
 /**
- * @param {!ChildProcess} chromeProcess
+ * @param {!Puppeteer.ChildProcess} chromeProcess
  * @param {number} timeout
  * @return {!Promise<string>}
  */