docs(new): migrate Page.ts to TSDoc (part 0 / 2) (#6104)

* docs(new): migrate Page.ts to TSDoc (part 0 / 2)

Co-authored-by: Changhao Han <changhaohan@chromium.org>

docs/api.md

@@ -170,6 +170,8 @@
   * [page.waitForSelector(selector[, options])](#pagewaitforselectorselector-options)
   * [page.waitForXPath(xpath[, options])](#pagewaitforxpathxpath-options)
   * [page.workers()](#pageworkers)
+  * [GeolocationOptions](#geolocationoptions)
+  * [WaitTimeoutOptions](#waittimeoutoptions)
 - [class: WebWorker](#class-webworker)
   * [webWorker.evaluate(pageFunction[, ...args])](#webworkerevaluatepagefunction-args)
   * [webWorker.evaluateHandle(pageFunction[, ...args])](#webworkerevaluatehandlepagefunction-args)
@@ -1900,10 +1902,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` <[Object]>
+- `options` <[GeolocationOptions](####GeolocationOptions)>
-  - `latitude` <[number]> Latitude between -90 and 90.
-  - `longitude` <[number]> Longitude between -180 and 180.
-  - `accuracy` <[number]> Optional non-negative accuracy value.
 - returns: <[Promise]>
 
 Sets the page's geolocation.
@@ -2077,8 +2076,7 @@ await page.waitFor(selector => !!document.querySelector(selector), {}, selector)
 Shortcut for [page.mainFrame().waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#framewaitforselectororfunctionortimeout-options-args).
 
 #### page.waitForFileChooser([options])
-- `options` <[Object]> Optional waiting parameters
+- `options` <[WaitTimeoutOptions](####WaitTimeoutOptions)> Optional waiting parameters
-  - `timeout` <[number]> Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to disable the timeout. The default value can be changed by using the [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) method.
 - returns: <[Promise]<[FileChooser]>> A promise that resolves after a page requests a file picker.
 
 > **NOTE** In non-headless Chromium, this method results in the native file picker dialog **not showing up** for the user.
@@ -2263,6 +2261,15 @@ This method returns all of the dedicated [WebWorkers](https://developer.mozilla.
 
 > **NOTE** This does not contain ServiceWorkers
 
+#### GeolocationOptions
+- `latitude` <[number]> Latitude between -90 and 90.
+- `longitude` <[number]> Longitude between -180 and 180.
+- `accuracy` <[number]> Optional non-negative accuracy value.
+
+#### WaitTimeoutOptions
+- `timeout` <[number]> Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to disable the timeout. The default value can be changed by using the [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) method.
+
+
 ### class: WebWorker
 
 The WebWorker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API).

new-docs/puppeteer.geolocationoptions.accuracy.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [GeolocationOptions](./puppeteer.geolocationoptions.md) &gt; [accuracy](./puppeteer.geolocationoptions.accuracy.md)
+
+## GeolocationOptions.accuracy property
+
+Optional non-negative accuracy value.
+
+<b>Signature:</b>
+
+```typescript
+accuracy?: number;
+```

new-docs/puppeteer.geolocationoptions.latitude.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [GeolocationOptions](./puppeteer.geolocationoptions.md) &gt; [latitude](./puppeteer.geolocationoptions.latitude.md)
+
+## GeolocationOptions.latitude property
+
+Longitude between -180 and 180.
+
+<b>Signature:</b>
+
+```typescript
+latitude: number;
+```

new-docs/puppeteer.geolocationoptions.longitude.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [GeolocationOptions](./puppeteer.geolocationoptions.md) &gt; [longitude](./puppeteer.geolocationoptions.longitude.md)
+
+## GeolocationOptions.longitude property
+
+Latitude between -90 and 90.
+
+<b>Signature:</b>
+
+```typescript
+longitude: number;
+```

new-docs/puppeteer.geolocationoptions.md

@@ -0,0 +1,21 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [GeolocationOptions](./puppeteer.geolocationoptions.md)
+
+## GeolocationOptions interface
+
+
+<b>Signature:</b>
+
+```typescript
+export interface GeolocationOptions 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [accuracy](./puppeteer.geolocationoptions.accuracy.md) | number | Optional non-negative accuracy value. |
+|  [latitude](./puppeteer.geolocationoptions.latitude.md) | number | Longitude between -180 and 180. |
+|  [longitude](./puppeteer.geolocationoptions.longitude.md) | number | Latitude between -90 and 90. |
+

new-docs/puppeteer.md

@@ -52,6 +52,7 @@
 |  [BrowserFetcherOptions](./puppeteer.browserfetcheroptions.md) |  |
 |  [ClickOptions](./puppeteer.clickoptions.md) |  |
 |  [ConsoleMessageLocation](./puppeteer.consolemessagelocation.md) |  |
+|  [GeolocationOptions](./puppeteer.geolocationoptions.md) |  |
 |  [JSONObject](./puppeteer.jsonobject.md) |  |
 |  [KeyDefinition](./puppeteer.keydefinition.md) | Copyright 2017 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. |
 |  [Metrics](./puppeteer.metrics.md) |  |
@@ -59,7 +60,9 @@
 |  [RemoteAddress](./puppeteer.remoteaddress.md) |  |
 |  [SerializedAXNode](./puppeteer.serializedaxnode.md) | Represents a Node and the properties of it that are relevant to Accessibility. |
 |  [SnapshotOptions](./puppeteer.snapshotoptions.md) |  |
+|  [WaitForOptions](./puppeteer.waitforoptions.md) |  |
 |  [WaitForTargetOptions](./puppeteer.waitfortargetoptions.md) |  |
+|  [WaitTimeoutOptions](./puppeteer.waittimeoutoptions.md) |  |
 
 ## Variables
 

new-docs/puppeteer.metrics.md

@@ -4,6 +4,7 @@
 
 ## Metrics interface
 
+
 <b>Signature:</b>
 
 ```typescript

new-docs/puppeteer.page._.md

@@ -4,6 +4,8 @@
 
 ## Page.$() method
 
+Runs `document.querySelector` within the page. If no element matches the selector, the return value resolves to `null`<!-- -->.
+
 <b>Signature:</b>
 
 ```typescript
@@ -14,9 +16,13 @@ $(selector: string): Promise<ElementHandle | null>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  selector | string |  |
+|  selector | string | A [selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) to query page for. |
 
 <b>Returns:</b>
 
 Promise&lt;[ElementHandle](./puppeteer.elementhandle.md) \| null&gt;
 
+## Remarks
+
+Shortcut for [Page.mainFrame().$(selector)](./puppeteer.frame._.md)<!-- -->.
+

new-docs/puppeteer.page.browser.md

@@ -13,3 +13,5 @@ browser(): Browser;
 
 [Browser](./puppeteer.browser.md)
 
+The browser this page belongs to.
+

new-docs/puppeteer.page.browsercontext.md

@@ -13,3 +13,5 @@ browserContext(): BrowserContext;
 
 [BrowserContext](./puppeteer.browsercontext.md)
 
+The browser context that the page belongs to
+

new-docs/puppeteer.page.frames.md

@@ -13,3 +13,5 @@ frames(): Frame[];
 
 [Frame](./puppeteer.frame.md)<!-- -->\[\]
 
+An array of all frames attached to the page.
+

new-docs/puppeteer.page.goback.md

@@ -14,7 +14,7 @@ goBack(options?: WaitForOptions): Promise<HTTPResponse | null>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  options | WaitForOptions |  |
+|  options | [WaitForOptions](./puppeteer.waitforoptions.md) |  |
 
 <b>Returns:</b>
 

new-docs/puppeteer.page.goforward.md

@@ -14,7 +14,7 @@ goForward(options?: WaitForOptions): Promise<HTTPResponse | null>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  options | WaitForOptions |  |
+|  options | [WaitForOptions](./puppeteer.waitforoptions.md) |  |
 
 <b>Returns:</b>
 

new-docs/puppeteer.page.goto.md

@@ -17,7 +17,7 @@ goto(url: string, options?: WaitForOptions & {
 |  Parameter | Type | Description |
 |  --- | --- | --- |
 |  url | string |  |
-|  options | WaitForOptions & { referer?: string; } |  |
+|  options | [WaitForOptions](./puppeteer.waitforoptions.md) & { referer?: string; } |  |
 
 <b>Returns:</b>
 

new-docs/puppeteer.page.isjavascriptenabled.md

@@ -13,3 +13,5 @@ isJavaScriptEnabled(): boolean;
 
 boolean
 
+`true` if the page has JavaScript enabled, `false` otherwise.
+

new-docs/puppeteer.page.mainframe.md

@@ -13,3 +13,5 @@ mainFrame(): Frame;
 
 [Frame](./puppeteer.frame.md)
 
+The page's main frame.
+

new-docs/puppeteer.page.md

@@ -70,7 +70,7 @@ page.off('request', logRequest);
 
 |  Method | Modifiers | Description |
 |  --- | --- | --- |
-|  [$(selector)](./puppeteer.page._.md) |  |  |
+|  [$(selector)](./puppeteer.page._.md) |  | Runs <code>document.querySelector</code> within the page. If no element matches the selector, the return value resolves to <code>null</code>. |
 |  [$$(selector)](./puppeteer.page.__.md) |  |  |
 |  [$$eval(selector, pageFunction, args)](./puppeteer.page.__eval.md) |  |  |
 |  [$eval(selector, pageFunction, args)](./puppeteer.page._eval.md) |  |  |
@@ -117,7 +117,7 @@ page.off('request', logRequest);
 |  [setDefaultNavigationTimeout(timeout)](./puppeteer.page.setdefaultnavigationtimeout.md) |  |  |
 |  [setDefaultTimeout(timeout)](./puppeteer.page.setdefaulttimeout.md) |  |  |
 |  [setExtraHTTPHeaders(headers)](./puppeteer.page.setextrahttpheaders.md) |  |  |
-|  [setGeolocation(options)](./puppeteer.page.setgeolocation.md) |  |  |
+|  [setGeolocation(options)](./puppeteer.page.setgeolocation.md) |  | Sets the page's geolocation. |
 |  [setJavaScriptEnabled(enabled)](./puppeteer.page.setjavascriptenabled.md) |  |  |
 |  [setOfflineMode(enabled)](./puppeteer.page.setofflinemode.md) |  |  |
 |  [setRequestInterception(value)](./puppeteer.page.setrequestinterception.md) |  |  |

new-docs/puppeteer.page.reload.md

@@ -14,7 +14,7 @@ reload(options?: WaitForOptions): Promise<HTTPResponse | null>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  options | WaitForOptions |  |
+|  options | [WaitForOptions](./puppeteer.waitforoptions.md) |  |
 
 <b>Returns:</b>
 

new-docs/puppeteer.page.setcontent.md

@@ -15,7 +15,7 @@ setContent(html: string, options?: WaitForOptions): Promise<void>;
 |  Parameter | Type | Description |
 |  --- | --- | --- |
 |  html | string |  |
-|  options | WaitForOptions |  |
+|  options | [WaitForOptions](./puppeteer.waitforoptions.md) |  |
 
 <b>Returns:</b>
 

new-docs/puppeteer.page.setdefaultnavigationtimeout.md

@@ -14,7 +14,7 @@ setDefaultNavigationTimeout(timeout: number): void;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  timeout | number |  |
+|  timeout | number | Maximum navigation time in milliseconds. |
 
 <b>Returns:</b>
 

new-docs/puppeteer.page.setdefaulttimeout.md

@@ -14,7 +14,7 @@ setDefaultTimeout(timeout: number): void;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  timeout | number |  |
+|  timeout | number | Maximum time in milliseconds. |
 
 <b>Returns:</b>
 

new-docs/puppeteer.page.setgeolocation.md

@@ -4,23 +4,33 @@
 
 ## Page.setGeolocation() method
 
+Sets the page's geolocation.
+
 <b>Signature:</b>
 
 ```typescript
-setGeolocation(options: {
+setGeolocation(options: GeolocationOptions): Promise<void>;
-        longitude: number;
-        latitude: number;
-        accuracy?: number;
-    }): Promise<void>;
 ```
 
 ## Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  options | { longitude: number; latitude: number; accuracy?: number; } |  |
+|  options | [GeolocationOptions](./puppeteer.geolocationoptions.md) |  |
 
 <b>Returns:</b>
 
 Promise&lt;void&gt;
 
+## Remarks
+
+Consider using [BrowserContext.overridePermissions()](./puppeteer.browsercontext.overridepermissions.md) to grant permissions for the page to read its geolocation.
+
+## Example
+
+
+```js
+await page.setGeolocation({latitude: 59.95, longitude: 30.31667});
+
+```
+

new-docs/puppeteer.page.setofflinemode.md

@@ -14,7 +14,7 @@ setOfflineMode(enabled: boolean): Promise<void>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  enabled | boolean |  |
+|  enabled | boolean | When <code>true</code>, enables offline mode for the page. |
 
 <b>Returns:</b>
 

new-docs/puppeteer.page.setrequestinterception.md

@@ -14,9 +14,40 @@ setRequestInterception(value: boolean): Promise<void>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  value | boolean |  |
+|  value | boolean | Whether to enable request interception. |
 
 <b>Returns:</b>
 
 Promise&lt;void&gt;
 
+## Remarks
+
+Activating request interception enables [HTTPRequest.abort()](./puppeteer.httprequest.abort.md)<!-- -->, [HTTPRequest.continue()](./puppeteer.httprequest.continue.md) and [HTTPRequest.respond()](./puppeteer.httprequest.respond.md) methods. This provides the capability to modify network requests that are made by a page.
+
+Once request interception is enabled, every request will stall unless it's continued, responded or aborted.
+
+\*\*NOTE\*\* Enabling request interception disables page caching.
+
+## Example
+
+An example of a naïve request interceptor that aborts all image requests:
+
+```js
+const puppeteer = require('puppeteer');
+(async () => {
+  const browser = await puppeteer.launch();
+  const page = await browser.newPage();
+  await page.setRequestInterception(true);
+  page.on('request', interceptedRequest => {
+    if (interceptedRequest.url().endsWith('.png') ||
+        interceptedRequest.url().endsWith('.jpg'))
+      interceptedRequest.abort();
+    else
+      interceptedRequest.continue();
+    });
+  await page.goto('https://example.com');
+  await browser.close();
+})();
+
+```
+

new-docs/puppeteer.page.target.md

@@ -13,3 +13,5 @@ target(): Target;
 
 [Target](./puppeteer.target.md)
 
+A target this page was created from.
+

new-docs/puppeteer.page.waitforfilechooser.md

@@ -7,18 +7,18 @@
 <b>Signature:</b>
 
 ```typescript
-waitForFileChooser(options?: {
+waitForFileChooser(options?: WaitTimeoutOptions): Promise<FileChooser>;
-        timeout?: number;
-    }): Promise<FileChooser>;
 ```
 
 ## Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  options | { timeout?: number; } |  |
+|  options | [WaitTimeoutOptions](./puppeteer.waittimeoutoptions.md) | Optional waiting parameters |
 
 <b>Returns:</b>
 
 Promise&lt;[FileChooser](./puppeteer.filechooser.md)<!-- -->&gt;
 
+Resolves after a page requests a file picker.
+

new-docs/puppeteer.page.waitfornavigation.md

@@ -14,7 +14,7 @@ waitForNavigation(options?: WaitForOptions): Promise<HTTPResponse | null>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  options | WaitForOptions |  |
+|  options | [WaitForOptions](./puppeteer.waitforoptions.md) |  |
 
 <b>Returns:</b>
 

new-docs/puppeteer.page.workers.md

@@ -13,3 +13,5 @@ workers(): WebWorker[];
 
 [WebWorker](./puppeteer.webworker.md)<!-- -->\[\]
 
+all of the dedicated [WebWorkers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) associated with the page.
+

new-docs/puppeteer.waitforoptions.md

@@ -0,0 +1,20 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [WaitForOptions](./puppeteer.waitforoptions.md)
+
+## WaitForOptions interface
+
+
+<b>Signature:</b>
+
+```typescript
+export interface WaitForOptions 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [timeout](./puppeteer.waitforoptions.timeout.md) | number | Maximum wait time in milliseconds, defaults to 30 seconds, pass <code>0</code> to disable the timeout. |
+|  [waitUntil](./puppeteer.waitforoptions.waituntil.md) | PuppeteerLifeCycleEvent \| PuppeteerLifeCycleEvent\[\] |  |
+

new-docs/puppeteer.waitforoptions.timeout.md

@@ -0,0 +1,18 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [WaitForOptions](./puppeteer.waitforoptions.md) &gt; [timeout](./puppeteer.waitforoptions.timeout.md)
+
+## WaitForOptions.timeout property
+
+Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to disable the timeout.
+
+<b>Signature:</b>
+
+```typescript
+timeout?: number;
+```
+
+## Remarks
+
+The default value can be changed by using the [Page.setDefaultTimeout()](./puppeteer.page.setdefaulttimeout.md) or [Page.setDefaultNavigationTimeout()](./puppeteer.page.setdefaultnavigationtimeout.md) methods.
+

new-docs/puppeteer.waitforoptions.waituntil.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [WaitForOptions](./puppeteer.waitforoptions.md) &gt; [waitUntil](./puppeteer.waitforoptions.waituntil.md)
+
+## WaitForOptions.waitUntil property
+
+<b>Signature:</b>
+
+```typescript
+waitUntil?: PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[];
+```

new-docs/puppeteer.waittimeoutoptions.md

@@ -0,0 +1,19 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [WaitTimeoutOptions](./puppeteer.waittimeoutoptions.md)
+
+## WaitTimeoutOptions interface
+
+
+<b>Signature:</b>
+
+```typescript
+export interface WaitTimeoutOptions 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [timeout](./puppeteer.waittimeoutoptions.timeout.md) | number | Maximum wait time in milliseconds, defaults to 30 seconds, pass <code>0</code> to disable the timeout. |
+

new-docs/puppeteer.waittimeoutoptions.timeout.md

@@ -0,0 +1,18 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [WaitTimeoutOptions](./puppeteer.waittimeoutoptions.md) &gt; [timeout](./puppeteer.waittimeoutoptions.timeout.md)
+
+## WaitTimeoutOptions.timeout property
+
+Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to disable the timeout.
+
+<b>Signature:</b>
+
+```typescript
+timeout?: number;
+```
+
+## Remarks
+
+The default value can be changed by using the [Page.setDefaultTimeout()](./puppeteer.page.setdefaulttimeout.md) method.
+

src/common/Page.ts

@@ -46,6 +46,9 @@ import { EvaluateFn, SerializableOrJSHandle } from './EvalTypes';
 
 const writeFileAsync = promisify(fs.writeFile);
 
+/**
+ * @public
+ */
 export interface Metrics {
   Timestamp?: number;
   Documents?: number;
@@ -62,11 +65,56 @@ export interface Metrics {
   JSHeapTotalSize?: number;
 }
 
-interface WaitForOptions {
+/**
+ * @public
+ */
+export interface WaitTimeoutOptions {
+  /**
+   * Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to
+   * disable the timeout.
+   *
+   * @remarks
+   * The default value can be changed by using the
+   * {@link Page.setDefaultTimeout} method.
+   */
+  timeout?: number;
+}
+
+/**
+ * @public
+ */
+export interface WaitForOptions {
+  /**
+   * Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to
+   * disable the timeout.
+   *
+   * @remarks
+   * The default value can be changed by using the
+   * {@link Page.setDefaultTimeout} or {@link Page.setDefaultNavigationTimeout}
+   * methods.
+   */
   timeout?: number;
   waitUntil?: PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[];
 }
 
+/**
+ * @public
+ */
+export interface GeolocationOptions {
+  /**
+   * Latitude between -90 and 90.
+   */
+  longitude: number;
+  /**
+   * Longitude between -180 and 180.
+   */
+  latitude: number;
+  /**
+   * Optional non-negative accuracy value.
+   */
+  accuracy?: number;
+}
+
 interface MediaFeature {
   name: string;
   value: string;
@@ -141,6 +189,8 @@ type VisionDeficiency =
 
 /**
  * All the events that a page instance may emit.
+ *
+ * @public
  */
 export const enum PageEmittedEvents {
   /**
@@ -243,7 +293,8 @@ export class Page extends EventEmitter {
   private _viewport: Viewport | null;
   private _screenshotTaskQueue: ScreenshotTaskQueue;
   private _workers = new Map<string, WebWorker>();
-  // TODO: improve this typedef - it's a function that takes a file chooser or something?
+  // TODO: improve this typedef - it's a function that takes a file chooser or
+  // something?
   private _fileChooserInterceptors = new Set<Function>();
 
   private _disconnectPromise?: Promise<Error>;
@@ -369,12 +420,19 @@ export class Page extends EventEmitter {
     for (const interceptor of interceptors) interceptor.call(null, fileChooser);
   }
 
+  /**
+   * @returns `true` if the page has JavaScript enabled, `false` otherwise.
+   */
   public isJavaScriptEnabled(): boolean {
     return this._javascriptEnabled;
   }
 
+  /**
+   * @param options - Optional waiting parameters
+   * @returns Resolves after a page requests a file picker.
+   */
   async waitForFileChooser(
-    options: { timeout?: number } = {}
+    options: WaitTimeoutOptions = {}
   ): Promise<FileChooser> {
     if (!this._fileChooserInterceptors.size)
       await this._client.send('Page.setInterceptFileChooserDialog', {
@@ -397,11 +455,19 @@ export class Page extends EventEmitter {
       });
   }
 
-  async setGeolocation(options: {
+  /**
-    longitude: number;
+   * Sets the page's geolocation.
-    latitude: number;
+   *
-    accuracy?: number;
+   * @remarks
-  }): Promise<void> {
+   * Consider using {@link BrowserContext.overridePermissions} to grant
+   * permissions for the page to read its geolocation.
+   *
+   * @example
+   * ```js
+   * await page.setGeolocation({latitude: 59.95, longitude: 30.31667});
+   * ```
+   */
+  async setGeolocation(options: GeolocationOptions): Promise<void> {
     const { longitude, latitude, accuracy = 0 } = options;
     if (longitude < -180 || longitude > 180)
       throw new Error(
@@ -422,14 +488,23 @@ export class Page extends EventEmitter {
     });
   }
 
+  /**
+   * @returns A target this page was created from.
+   */
   target(): Target {
     return this._target;
   }
 
+  /**
+   * @returns The browser this page belongs to.
+   */
   browser(): Browser {
     return this._target.browser();
   }
 
+  /**
+   * @returns The browser context that the page belongs to
+   */
   browserContext(): BrowserContext {
     return this._target.browserContext();
   }
@@ -448,6 +523,9 @@ export class Page extends EventEmitter {
       );
   }
 
+  /**
+   * @returns The page's main frame.
+   */
   mainFrame(): Frame {
     return this._frameManager.mainFrame();
   }
@@ -472,30 +550,91 @@ export class Page extends EventEmitter {
     return this._accessibility;
   }
 
+  /**
+   * @returns An array of all frames attached to the page.
+   */
   frames(): Frame[] {
     return this._frameManager.frames();
   }
 
+  /**
+   * @returns all of the dedicated
+   * {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API | WebWorkers}
+   * associated with the page.
+   */
   workers(): WebWorker[] {
     return Array.from(this._workers.values());
   }
 
+  /**
+   * @param value - Whether to enable request interception.
+   *
+   * @remarks
+   * Activating request interception enables {@link HTTPRequest.abort},
+   * {@link HTTPRequest.continue} and {@link HTTPRequest.respond} methods.  This
+   * provides the capability to modify network requests that are made by a page.
+   *
+   * Once request interception is enabled, every request will stall unless it's
+   * continued, responded or aborted.
+   *
+   * **NOTE** Enabling request interception disables page caching.
+   *
+   * @example
+   * An example of a naïve request interceptor that aborts all image requests:
+   * ```js
+   * const puppeteer = require('puppeteer');
+   * (async () => {
+   *   const browser = await puppeteer.launch();
+   *   const page = await browser.newPage();
+   *   await page.setRequestInterception(true);
+   *   page.on('request', interceptedRequest => {
+   *     if (interceptedRequest.url().endsWith('.png') ||
+   *         interceptedRequest.url().endsWith('.jpg'))
+   *       interceptedRequest.abort();
+   *     else
+   *       interceptedRequest.continue();
+   *     });
+   *   await page.goto('https://example.com');
+   *   await browser.close();
+   * })();
+   * ```
+   */
   async setRequestInterception(value: boolean): Promise<void> {
     return this._frameManager.networkManager().setRequestInterception(value);
   }
 
+  /**
+   * @param enabled - When `true`, enables offline mode for the page.
+   */
   setOfflineMode(enabled: boolean): Promise<void> {
     return this._frameManager.networkManager().setOfflineMode(enabled);
   }
 
+  /**
+   * @param timeout - Maximum navigation time in milliseconds.
+   */
   setDefaultNavigationTimeout(timeout: number): void {
     this._timeoutSettings.setDefaultNavigationTimeout(timeout);
   }
 
+  /**
+   * @param timeout - Maximum time in milliseconds.
+   */
   setDefaultTimeout(timeout: number): void {
     this._timeoutSettings.setDefaultTimeout(timeout);
   }
 
+  /**
+   * Runs `document.querySelector` within the page. If no element matches the
+   * selector, the return value resolves to `null`.
+   *
+   * @remarks
+   * Shortcut for {@link Frame.$ | Page.mainFrame().$(selector) }.
+   *
+   * @param selector - A
+   * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors | selector}
+   * to query page for.
+   */
   async $(selector: string): Promise<ElementHandle | null> {
     return this.mainFrame().$(selector);
   }