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

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

Co-authored-by: Changhao Han <[email protected]>

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]>
-  - `latitude` <[number]> Latitude between -90 and 90.
-  - `longitude` <[number]> Longitude between -180 and 180.
-  - `accuracy` <[number]> Optional non-negative accuracy value.
+- `options` <[GeolocationOptions](####GeolocationOptions)>
 - 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
-  - `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.
+- `options` <[WaitTimeoutOptions](####WaitTimeoutOptions)> Optional waiting parameters
 - 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,14 +52,17 @@
 |  [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) |  |
 |  [PressOptions](./puppeteer.pressoptions.md) |  |
 |  [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: {
-        longitude: number;
-        latitude: number;
-        accuracy?: number;
-    }): Promise<void>;
+setGeolocation(options: GeolocationOptions): 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?: {
-        timeout?: number;
-    }): Promise<FileChooser>;
+waitForFileChooser(options?: WaitTimeoutOptions): 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.
+