chore: Introduce API Extractor and start generating documentation (#5967

)

.gitignore

@@ -15,3 +15,4 @@ yarn.lock
 /utils/browser/puppeteer-web.js
 /lib
 test/coverage.json
+temp/

api-extractor.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "mainEntryPointFilePath": "<projectFolder>/lib/api-docs-entry.d.ts",
+  "bundledPackages": [ ],
+
+  "apiReport": {
+    "enabled": false
+  },
+
+  "docModel": {
+    "enabled": true
+  },
+
+  "dtsRollup": {
+    "enabled": false
+  },
+
+  "tsdocMetadata": {
+    "enabled": false
+  },
+
+  "messages": {
+    "compilerMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      }
+    },
+
+    "extractorMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      }
+    },
+
+    "tsdocMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      }
+    }
+  }
+
+}

package.json

@@ -31,7 +31,8 @@
     "apply-next-version": "node utils/apply_next_version.js",
     "update-protocol-d-ts": "node utils/protocol-types-generator update",
     "compare-protocol-d-ts": "node utils/protocol-types-generator compare",
-    "test-install": "scripts/test-install.sh"
+    "test-install": "scripts/test-install.sh",
+    "generate-docs": "npm run tsc && api-extractor run --local --verbose && api-documenter markdown -i temp -o new-docs"
   },
   "files": [
     "lib/",
@@ -56,6 +57,8 @@
     "ws": "^7.2.3"
   },
   "devDependencies": {
+    "@microsoft/api-documenter": "^7.8.8",
+    "@microsoft/api-extractor": "^7.8.8",
     "@types/debug": "0.0.31",
     "@types/mime": "^2.0.0",
     "@types/node": "^10.17.14",

src/Browser.ts

@@ -22,7 +22,7 @@ import Protocol from './protocol';
 import { Connection } from './Connection';
 import { Page } from './Page';
 import { ChildProcess } from 'child_process';
-import type { Viewport } from './PuppeteerViewport';
+import { Viewport } from './PuppeteerViewport';
 
 type BrowserCloseCallback = () => Promise<void> | void;
 

src/Connection.ts

@@ -19,7 +19,7 @@ import * as debug from 'debug';
 const debugProtocol = debug('puppeteer:protocol');
 
 import Protocol from './protocol';
-import type { ConnectionTransport } from './ConnectionTransport';
+import { ConnectionTransport } from './ConnectionTransport';
 import * as EventEmitter from 'events';
 
 interface ConnectionCallback {

src/EmulationManager.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 import { CDPSession } from './Connection';
-import type { Viewport } from './PuppeteerViewport';
+import { Viewport } from './PuppeteerViewport';
 import Protocol from './protocol';
 
 export class EmulationManager {

src/Launcher.ts

@@ -24,14 +24,14 @@ import { BrowserFetcher } from './BrowserFetcher';
 import { Connection } from './Connection';
 import { Browser } from './Browser';
 import { helper, assert, debugError } from './helper';
-import type { ConnectionTransport } from './ConnectionTransport';
+import { ConnectionTransport } from './ConnectionTransport';
 import { WebSocketTransport } from './WebSocketTransport';
 import { BrowserRunner } from './launcher/BrowserRunner';
 
 const mkdtempAsync = helper.promisify(fs.mkdtemp);
 const writeFileAsync = helper.promisify(fs.writeFile);
 
-import type {
+import {
   ChromeArgOptions,
   LaunchOptions,
   BrowserOptions,

src/Page.ts

@@ -30,7 +30,7 @@ import { WebWorker } from './WebWorker';
 import { Browser, BrowserContext } from './Browser';
 import { Target } from './Target';
 import { createJSHandle, JSHandle, ElementHandle } from './JSHandle';
-import type { Viewport } from './PuppeteerViewport';
+import { Viewport } from './PuppeteerViewport';
 import { Credentials } from './NetworkManager';
 import { HTTPRequest } from './HTTPRequest';
 import { HTTPResponse } from './HTTPResponse';

src/PipeTransport.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 import { helper, debugError, PuppeteerEventListener } from './helper';
-import type { ConnectionTransport } from './ConnectionTransport';
+import { ConnectionTransport } from './ConnectionTransport';
 
 export class PipeTransport implements ConnectionTransport {
   _pipeWrite: NodeJS.WritableStream;

src/Puppeteer.ts

@@ -14,21 +14,31 @@
  * limitations under the License.
  */
 import Launcher from './Launcher';
-import type {
+import {
   LaunchOptions,
   ChromeArgOptions,
   BrowserOptions,
 } from './launcher/LaunchOptions';
-import type { ProductLauncher } from './Launcher';
+import { ProductLauncher } from './Launcher';
 import { BrowserFetcher, BrowserFetcherOptions } from './BrowserFetcher';
 import { puppeteerErrors, PuppeteerErrors } from './Errors';
-import type { ConnectionTransport } from './ConnectionTransport';
+import { ConnectionTransport } from './ConnectionTransport';
 
 import { devicesMap } from './DeviceDescriptors';
-import type { DevicesMap } from './/DeviceDescriptors';
+import { DevicesMap } from './/DeviceDescriptors';
 import { Browser } from './Browser';
-import * as QueryHandler from './QueryHandler';
+import {
+  registerCustomQueryHandler,
+  unregisterCustomQueryHandler,
+  customQueryHandlers,
+  clearQueryHandlers,
+  QueryHandler,
+} from './QueryHandler';
 
+/**
+ * The main Puppeteer class
+ * @public
+ */
 export class Puppeteer {
   _projectRoot: string;
   _preferredRevision: string;
@@ -135,23 +145,23 @@ export class Puppeteer {
   // eslint-disable-next-line @typescript-eslint/camelcase
   __experimental_registerCustomQueryHandler(
     name: string,
-    queryHandler: QueryHandler.QueryHandler
+    queryHandler: QueryHandler
   ): void {
-    QueryHandler.registerCustomQueryHandler(name, queryHandler);
+    registerCustomQueryHandler(name, queryHandler);
   }
 
   // eslint-disable-next-line @typescript-eslint/camelcase
   __experimental_unregisterCustomQueryHandler(name: string): void {
-    QueryHandler.unregisterCustomQueryHandler(name);
+    unregisterCustomQueryHandler(name);
   }
 
   // eslint-disable-next-line @typescript-eslint/camelcase
-  __experimental_customQueryHandlers(): Map<string, QueryHandler.QueryHandler> {
-    return QueryHandler.customQueryHandlers();
+  __experimental_customQueryHandlers(): Map<string, QueryHandler> {
+    return customQueryHandlers();
   }
 
   // eslint-disable-next-line @typescript-eslint/camelcase
   __experimental_clearQueryHandlers(): void {
-    QueryHandler.clearQueryHandlers();
+    clearQueryHandlers();
   }
 }

src/QueryHandler.ts

@@ -74,11 +74,3 @@ export function getQueryHandlerAndSelector(
     queryHandler,
   };
 }
-
-module.exports = {
-  registerCustomQueryHandler,
-  unregisterCustomQueryHandler,
-  customQueryHandlers,
-  getQueryHandlerAndSelector,
-  clearQueryHandlers,
-};

src/Target.ts

@@ -19,7 +19,7 @@ import { Page } from './Page';
 import { WebWorker } from './WebWorker';
 import { CDPSession } from './Connection';
 import { Browser, BrowserContext } from './Browser';
-import type { Viewport } from './PuppeteerViewport';
+import { Viewport } from './PuppeteerViewport';
 import Protocol from './protocol';
 
 export class Target {

src/WebSocketTransport.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 import * as NodeWebSocket from 'ws';
-import type { ConnectionTransport } from './ConnectionTransport';
+import { ConnectionTransport } from './ConnectionTransport';
 
 export class WebSocketTransport implements ConnectionTransport {
   static create(url: string): Promise<WebSocketTransport> {

src/api-docs-entry.ts

@@ -0,0 +1,47 @@
+/**
+ * Copyright 2020 Google Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*
+ * This file re-exports any APIs that we want to have documentation generated for.
+ * It is used by API Extractor to determine what parts of the system to document.
+ *
+ * We also have src/api.ts. This is used in `index.js` and by the legacy DocLint system.
+ * src/api-docs-entry.ts is ONLY used by API Extractor.
+ *
+ * Once we have migrated to API Extractor and removed DocLint we can remove the duplication and use this file.
+ */
+export * from './Accessibility';
+export * from './Browser';
+export * from './BrowserFetcher';
+export * from './Connection';
+export * from './ConsoleMessage';
+export * from './Coverage';
+export * from './Dialog';
+export * from './JSHandle';
+export * from './ExecutionContext';
+export * from './FileChooser';
+export * from './FrameManager';
+export * from './JSHandle';
+export * from './Input';
+export * from './Page';
+export * from './Puppeteer';
+export * from './HTTPRequest';
+export * from './HTTPResponse';
+export * from './SecurityDetails';
+export * from './Target';
+export * from './Errors';
+export * from './Tracing';
+export * from './WebWorker';

src/launcher/BrowserRunner.ts

@@ -19,7 +19,7 @@ import * as debug from 'debug';
 import * as removeFolder from 'rimraf';
 import * as childProcess from 'child_process';
 import { helper, assert, debugError } from '../helper';
-import type { LaunchOptions } from './LaunchOptions';
+import { LaunchOptions } from './LaunchOptions';
 import { Connection } from '../Connection';
 import { WebSocketTransport } from '../WebSocketTransport';
 import { PipeTransport } from '../PipeTransport';

tsconfig.json

@@ -5,7 +5,9 @@
     "outDir": "./lib",
     "target": "ESNext",
     "moduleResolution": "node",
-    "module": "CommonJS"
+    "module": "CommonJS",
+    "declaration": true,
+    "declarationMap": true
   },
   "include": [
     "src"