docs: show experimental and remark blocks (#12363)

docs/api/index.md

@@ -23,6 +23,16 @@ Description
 
 The Accessibility class provides methods for inspecting the browser's accessibility tree. The accessibility tree is used by assistive technology such as [screen readers](https://en.wikipedia.org/wiki/Screen_reader) or [switches](https://en.wikipedia.org/wiki/Switch_access).
 
+**Remarks:**
+
+Accessibility is a very platform-specific thing. On different platforms, there are different screen readers that might have wildly different output.
+
+Blink - Chrome's rendering engine - has a concept of "accessibility tree", which is then translated into different platform-specific APIs. Accessibility namespace gives users access to the Blink Accessibility Tree.
+
+Most of the accessibility tree gets filtered out when converting from Blink AX Tree to Platform-specific AX-Tree or by assistive technologies themselves. By default, Puppeteer tries to approximate this filtering, exposing only the "interesting" nodes of the tree.
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Accessibility` class.
+
 </td></tr>
 <tr><td>
 
@@ -36,6 +46,10 @@ The Accessibility class provides methods for inspecting the browser's accessibil
 
 [Browser](./puppeteer.browser.md) [emits](./puppeteer.eventemitter.emit.md) various events which are documented in the [BrowserEvent](./puppeteer.browserevent.md) enum.
 
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Browser` class.
+
 </td></tr>
 <tr><td>
 
@@ -51,6 +65,10 @@ When a [browser](./puppeteer.browser.md) is launched, it has a single [browser c
 
 If a [page](./puppeteer.page.md) opens another [page](./puppeteer.page.md), e.g. using `window.open`, the popup will belong to the parent [page's browser context](./puppeteer.page.browsercontext.md).
 
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `BrowserContext` class.
+
 </td></tr>
 <tr><td>
 
@@ -60,6 +78,14 @@ If a [page](./puppeteer.page.md) opens another [page](./puppeteer.page.md), e.g.
 
 The `CDPSession` instances are used to talk raw Chrome Devtools Protocol.
 
+**Remarks:**
+
+Protocol methods can be called with [CDPSession.send()](./puppeteer.cdpsession.send.md) method and protocol events can be subscribed to with `CDPSession.on` method.
+
+Useful links: [DevTools Protocol Viewer](https://chromedevtools.github.io/devtools-protocol/) and [Getting Started with DevTools Protocol](https://github.com/aslushnikov/getting-started-with-cdp/blob/HEAD/README.md).
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `CDPSession` class.
+
 </td></tr>
 <tr><td>
 
@@ -85,6 +111,10 @@ ConsoleMessage objects are dispatched by page via the 'console' event.
 
 The Coverage class provides methods to gather information about parts of JavaScript and CSS that were used by the page.
 
+**Remarks:**
+
+To output coverage in a form consumable by [Istanbul](https://github.com/istanbuljs), see [puppeteer-to-istanbul](https://github.com/istanbuljs/puppeteer-to-istanbul).
+
 </td></tr>
 <tr><td>
 
@@ -101,6 +131,12 @@ The Coverage class provides methods to gather information about parts of JavaScr
 
 Device request prompts let you respond to the page requesting for a device through an API like WebBluetooth.
 
+**Remarks:**
+
+`DeviceRequestPrompt` instances are returned via the [Page.waitForDevicePrompt()](./puppeteer.page.waitfordeviceprompt.md) method.
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `DeviceRequestPrompt` class.
+
 </td></tr>
 <tr><td>
 
@@ -110,6 +146,10 @@ Device request prompts let you respond to the page requesting for a device throu
 
 Device in a request prompt.
 
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `DeviceRequestPromptDevice` class.
+
 </td></tr>
 <tr><td>
 
@@ -119,6 +159,10 @@ Device in a request prompt.
 
 Dialog instances are dispatched by the [Page](./puppeteer.page.md) via the `dialog` event.
 
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Dialog` class.
+
 </td></tr>
 <tr><td>
 
@@ -128,6 +172,31 @@ Dialog instances are dispatched by the [Page](./puppeteer.page.md) via the `dial
 
 ElementHandle represents an in-page DOM element.
 
+**Remarks:**
+
+ElementHandles can be created with the [Page.$()](./puppeteer.page._.md) method.
+
+```ts
+import puppeteer from 'puppeteer';
+
+(async () => {
+  const browser = await puppeteer.launch();
+  const page = await browser.newPage();
+  await page.goto('https://example.com');
+  const hrefElement = await page.$('a');
+  await hrefElement.click();
+  // ...
+})();
+```
+
+ElementHandle prevents the DOM element from being garbage-collected unless the handle is [disposed](./puppeteer.jshandle.dispose.md). ElementHandles are auto-disposed when their origin frame gets navigated.
+
+ElementHandle instances can be used as arguments in [Page.$eval()](./puppeteer.page._eval.md) and [Page.evaluate()](./puppeteer.page.evaluate.md) methods.
+
+If you're using TypeScript, ElementHandle takes a generic argument that denotes the type of element the handle is holding within. For example, if you have a handle to a `<select>` element, you can type it as `ElementHandle<HTMLSelectElement>` and you get some nicer type checks.
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `ElementHandle` class.
+
 </td></tr>
 <tr><td>
 
@@ -137,6 +206,12 @@ ElementHandle represents an in-page DOM element.
 
 The EventEmitter class that many Puppeteer classes extend.
 
+**Remarks:**
+
+This allows you to listen to events that Puppeteer classes fire and act accordingly. Therefore you'll mostly use [on](./puppeteer.eventemitter.on.md) and [off](./puppeteer.eventemitter.off.md) to bind and unbind to event listeners.
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `EventEmitter` class.
+
 </td></tr>
 <tr><td>
 
@@ -146,6 +221,14 @@ The EventEmitter class that many Puppeteer classes extend.
 
 File choosers let you react to the page requesting for a file.
 
+**Remarks:**
+
+`FileChooser` instances are returned via the [Page.waitForFileChooser()](./puppeteer.page.waitforfilechooser.md) method.
+
+In browsers, only one file chooser can be opened at a time. All file choosers must be accepted or canceled. Not doing so will prevent subsequent file choosers from appearing.
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `FileChooser` class.
+
 </td></tr>
 <tr><td>
 
@@ -157,6 +240,14 @@ Represents a DOM frame.
 
 To understand frames, you can think of frames as `<iframe>` elements. Just like iframes, frames can be nested, and when JavaScript is executed in a frame, the JavaScript does not effect frames inside the ambient frame the JavaScript executes in.
 
+**Remarks:**
+
+Frame lifecycles are controlled by three events that are all dispatched on the parent [page](./puppeteer.frame.page.md):
+
+- [PageEvent.FrameAttached](./puppeteer.pageevent.md) - [PageEvent.FrameNavigated](./puppeteer.pageevent.md) - [PageEvent.FrameDetached](./puppeteer.pageevent.md)
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Frame` class.
+
 </td></tr>
 <tr><td>
 
@@ -166,6 +257,26 @@ To understand frames, you can think of frames as `<iframe>` elements. Just like
 
 Represents an HTTP request sent by a page.
 
+**Remarks:**
+
+Whenever the page sends a request, such as for a network resource, the following events are emitted by Puppeteer's `page`:
+
+- `request`: emitted when the request is issued by the page. - `requestfinished` - emitted when the response body is downloaded and the request is complete.
+
+If request fails at some point, then instead of `requestfinished` event the `requestfailed` event is emitted.
+
+All of these events provide an instance of `HTTPRequest` representing the request that occurred:
+
+```
+page.on('request', request => ...)
+```
+
+NOTE: HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request will complete with `requestfinished` event.
+
+If request gets a 'redirect' response, the request is successfully finished with the `requestfinished` event, and a new request is issued to a redirected url.
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `HTTPRequest` class.
+
 </td></tr>
 <tr><td>
 
@@ -175,6 +286,10 @@ Represents an HTTP request sent by a page.
 
 The HTTPResponse class represents responses which are received by the [Page](./puppeteer.page.md) class.
 
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `HTTPResponse` class.
+
 </td></tr>
 <tr><td>
 
@@ -195,6 +310,10 @@ Handles prevent the referenced JavaScript object from being garbage-collected un
 
 Handles can be used as arguments for any evaluation function such as [Page.$eval()](./puppeteer.page._eval.md), [Page.evaluate()](./puppeteer.page.evaluate.md), and [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md). They are resolved to their referenced object.
 
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `JSHandle` class.
+
 </td></tr>
 <tr><td>
 
@@ -204,6 +323,14 @@ Handles can be used as arguments for any evaluation function such as [Page.$eval
 
 Keyboard provides an api for managing a virtual keyboard. The high level api is [Keyboard.type()](./puppeteer.keyboard.type.md), which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page.
 
+**Remarks:**
+
+For finer control, you can use [Keyboard.down()](./puppeteer.keyboard.down.md), [Keyboard.up()](./puppeteer.keyboard.up.md), and [Keyboard.sendCharacter()](./puppeteer.keyboard.sendcharacter.md) to manually fire events as if they were generated from a real keyboard.
+
+On macOS, keyboard shortcuts like `⌘ A` -&gt; Select All do not work. See [\#1313](https://github.com/puppeteer/puppeteer/issues/1313).
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Keyboard` class.
+
 </td></tr>
 <tr><td>
 
@@ -222,6 +349,12 @@ Locators describe a strategy of locating objects and performing an action on the
 
 The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport.
 
+**Remarks:**
+
+Every `page` object has its own Mouse, accessible with \[`page.mouse`\](\#pagemouse).
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Mouse` class.
+
 </td></tr>
 <tr><td>
 
@@ -237,6 +370,10 @@ One Browser instance might have multiple Page instances.
 
 :::
 
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Page` class.
+
 </td></tr>
 <tr><td>
 
@@ -246,6 +383,10 @@ One Browser instance might have multiple Page instances.
 
 Describes a launcher - a class that is able to create and launch a browser instance.
 
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `ProductLauncher` class.
+
 </td></tr>
 <tr><td>
 
@@ -266,6 +407,10 @@ The main Puppeteer class.
 
 IMPORTANT: if you are using Puppeteer in a Node environment, you will get an instance of [PuppeteerNode](./puppeteer.puppeteernode.md) when you import or require `puppeteer`. That class extends `Puppeteer`, so has all the methods documented below as well as all that are defined on [PuppeteerNode](./puppeteer.puppeteernode.md).
 
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Puppeteer` class.
+
 </td></tr>
 <tr><td>
 
@@ -275,6 +420,10 @@ IMPORTANT: if you are using Puppeteer in a Node environment, you will get an ins
 
 The base class for all Puppeteer-specific errors
 
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `PuppeteerError` class.
+
 </td></tr>
 <tr><td>
 
@@ -286,6 +435,14 @@ Extends the main [Puppeteer](./puppeteer.puppeteer.md) class with Node specific
 
 If you're using Puppeteer in a Node environment, this is the class you'll get when you run `require('puppeteer')` (or the equivalent ES `import`).
 
+**Remarks:**
+
+The most common method to use is [launch](./puppeteer.puppeteernode.launch.md), which is used to launch and connect to a new browser instance.
+
+See [the main Puppeteer class](./puppeteer.puppeteer.md) for methods common to all environments, such as [Puppeteer.connect()](./puppeteer.puppeteer.connect.md).
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `PuppeteerNode` class.
+
 </td></tr>
 <tr><td>
 
@@ -293,6 +450,10 @@ If you're using Puppeteer in a Node environment, this is the class you'll get wh
 
 </td><td>
 
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `ScreenRecorder` class.
+
 </td></tr>
 <tr><td>
 
@@ -302,6 +463,10 @@ If you're using Puppeteer in a Node environment, this is the class you'll get wh
 
 The SecurityDetails class represents the security details of a response that was received over a secure connection.
 
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `SecurityDetails` class.
+
 </td></tr>
 <tr><td>
 
@@ -311,6 +476,10 @@ The SecurityDetails class represents the security details of a response that was
 
 Target represents a [CDP target](https://chromedevtools.github.io/devtools-protocol/tot/Target/). In CDP a target is something that can be debugged such a frame, a page or a worker.
 
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Target` class.
+
 </td></tr>
 <tr><td>
 
@@ -320,6 +489,10 @@ Target represents a [CDP target](https://chromedevtools.github.io/devtools-proto
 
 TimeoutError is emitted whenever certain operations are terminated due to timeout.
 
+**Remarks:**
+
+Example operations are [page.waitForSelector](./puppeteer.page.waitforselector.md) or [puppeteer.launch](./puppeteer.puppeteernode.launch.md).
+
 </td></tr>
 <tr><td>
 
@@ -329,6 +502,10 @@ TimeoutError is emitted whenever certain operations are terminated due to timeou
 
 The Touchscreen class exposes touchscreen events.
 
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Touchscreen` class.
+
 </td></tr>
 <tr><td>
 
@@ -338,6 +515,12 @@ The Touchscreen class exposes touchscreen events.
 
 The Tracing class exposes the tracing audit interface.
 
+**Remarks:**
+
+You can use `tracing.start` and `tracing.stop` to create a trace file which can be opened in Chrome DevTools or [timeline viewer](https://chromedevtools.github.io/timeline-viewer/).
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Tracing` class.
+
 </td></tr>
 <tr><td>
 
@@ -356,6 +539,12 @@ Puppeteer will throw this error if a method is not supported by the currently us
 
 This class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API).
 
+**Remarks:**
+
+The events `workercreated` and `workerdestroyed` are emitted on the page object to signal the worker lifecycle.
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `WebWorker` class.
+
 </td></tr>
 </tbody></table>
 
@@ -713,6 +902,8 @@ Set of configurable options for CSS coverage.
 
 </td><td>
 
+**_(Experimental)_**
+
 </td></tr>
 <tr><td>
 
@@ -986,6 +1177,8 @@ Required response data to fulfill a request with.
 
 </td><td>
 
+**_(Experimental)_**
+
 </td></tr>
 <tr><td>
 
@@ -1389,6 +1582,32 @@ All the valid keys that can be passed to functions that take user input, such as
 
 All the valid paper format types when printing a PDF.
 
+**Remarks:**
+
+The sizes of each format are as follows:
+
+- `Letter`: 8.5in x 11in
+
+- `Legal`: 8.5in x 14in
+
+- `Tabloid`: 11in x 17in
+
+- `Ledger`: 17in x 11in
+
+- `A0`: 33.1in x 46.8in
+
+- `A1`: 23.4in x 33.1in
+
+- `A2`: 16.54in x 23.4in
+
+- `A3`: 11.7in x 16.54in
+
+- `A4`: 8.27in x 11.7in
+
+- `A5`: 5.83in x 8.27in
+
+- `A6`: 4.13in x 5.83in
+
 </td></tr>
 <tr><td>
 

docs/api/puppeteer.accessibility.md

@@ -47,5 +47,9 @@ Description
 
 Captures the current state of the accessibility tree. The returned object represents the root accessible node of the page.
 
+**Remarks:**
+
+**NOTE** The Chrome accessibility tree contains nodes that go unused on most platforms and by most screen readers. Puppeteer will discard them as well for an easier to process tree, unless `interestingOnly` is set to `false`.
+
 </td></tr>
 </tbody></table>

docs/api/puppeteer.browser.md

@@ -104,7 +104,11 @@ Whether Puppeteer is connected to this [browser](./puppeteer.browser.md).
 
 </td><td>
 
-Get debug information from Puppeteer.
+**_(Experimental)_** Get debug information from Puppeteer.
+
+**Remarks:**
+
+Currently, includes pending protocol calls. In the future, we might add more info.
 
 </td></tr>
 </tbody></table>
@@ -171,6 +175,10 @@ This won't share cookies/cache with other [browser contexts](./puppeteer.browser
 
 Gets the default [browser context](./puppeteer.browsercontext.md).
 
+**Remarks:**
+
+The default [browser context](./puppeteer.browsercontext.md) cannot be closed.
+
 </td></tr>
 <tr><td>
 
@@ -223,6 +231,10 @@ Gets a list of all open [pages](./puppeteer.page.md) inside this [Browser](./pup
 
 If there ar multiple [browser contexts](./puppeteer.browsercontext.md), this returns all [pages](./puppeteer.page.md) in all [browser contexts](./puppeteer.browsercontext.md).
 
+**Remarks:**
+
+Non-visible [pages](./puppeteer.page.md), such as `"background_page"`, will not be listed here. You can find them using [Target.page()](./puppeteer.target.page.md).
+
 </td></tr>
 <tr><td>
 
@@ -316,5 +328,9 @@ You can find the debugger URL (`webSocketDebuggerUrl`) from `http://HOST:PORT/js
 
 See [browser endpoint](https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target) for more information.
 
+**Remarks:**
+
+The format is always `ws://HOST:PORT/devtools/browser/<id>`.
+
 </td></tr>
 </tbody></table>

docs/api/puppeteer.browsercontext.md

@@ -141,6 +141,10 @@ Clears all permission overrides for this [browser context](./puppeteer.browserco
 
 Closes this [browser context](./puppeteer.browsercontext.md) and all associated [pages](./puppeteer.page.md).
 
+**Remarks:**
+
+The [default browser context](./puppeteer.browser.defaultbrowsercontext.md) cannot be closed.
+
 </td></tr>
 <tr><td>
 
@@ -193,6 +197,10 @@ Grants this [browser context](./puppeteer.browsercontext.md) the given `permissi
 
 Gets a list of all open [pages](./puppeteer.page.md) inside this [browser context](./puppeteer.browsercontext.md).
 
+**Remarks:**
+
+Non-visible [pages](./puppeteer.page.md), such as `"background_page"`, will not be listed here. You can find them using [Target.page()](./puppeteer.target.page.md).
+
 </td></tr>
 <tr><td>
 

docs/api/puppeteer.browserevent.md

@@ -54,6 +54,10 @@ TargetChanged
 
 Emitted when the URL of a target changes. Contains a [Target](./puppeteer.target.md) instance.
 
+**Remarks:**
+
+Note that this includes target changes in all browser contexts.
+
 </td></tr>
 <tr><td>
 
@@ -69,6 +73,10 @@ Emitted when a target is created, for example when a new page is opened by [wind
 
 Contains a [Target](./puppeteer.target.md) instance.
 
+**Remarks:**
+
+Note that this includes target creations in all browser contexts.
+
 </td></tr>
 <tr><td>
 
@@ -82,5 +90,9 @@ TargetDestroyed
 
 Emitted when a target is destroyed, for example when a page is closed. Contains a [Target](./puppeteer.target.md) instance.
 
+**Remarks:**
+
+Note that this includes target destructions in all browser contexts.
+
 </td></tr>
 </tbody></table>

docs/api/puppeteer.browserlaunchargumentoptions.md

@@ -110,6 +110,12 @@ boolean \| 'shell'
 
 Whether to run the browser in headless mode.
 
+**Remarks:**
+
+- `true` launches the browser in the [new headless](https://developer.chrome.com/articles/new-headless/) mode.
+
+- `'shell'` launches [shell](https://developer.chrome.com/blog/chrome-headless-shell) known as the old headless mode.
+
 </td><td>
 
 `true`

docs/api/puppeteer.configuration.md

@@ -128,6 +128,10 @@ Specifies the URL prefix that is used to download the browser.
 
 Can be overridden by `PUPPETEER_DOWNLOAD_BASE_URL`.
 
+**Remarks:**
+
+This must include the protocol and may even need a path prefix.
+
 </td><td>
 
 Either https://storage.googleapis.com/chrome-for-testing-public or https://archive.mozilla.org/pub/firefox/nightly/latest-mozilla-central, depending on the product.

docs/api/puppeteer.connectoptions.md

@@ -85,6 +85,10 @@ Record<string, string>
 
 Headers to use for the web socket connection.
 
+**Remarks:**
+
+Only works in the Node.js environment.
+
 </td><td>
 
 </td></tr>

docs/api/puppeteer.coverage.md

@@ -103,6 +103,10 @@ Description
 
 </td><td>
 
+**Remarks:**
+
+Anonymous scripts are ones that don't have an associated url. These are scripts that are dynamically created on the page using `eval` or `new Function`. If `reportAnonymousScripts` is set to `true`, anonymous scripts URL will start with `debugger://VM` (unless a magic //\# sourceURL comment is present, in which case that will the be URL).
+
 </td></tr>
 <tr><td>
 
@@ -114,6 +118,10 @@ Description
 
 Promise that resolves to the array of coverage reports for all stylesheets.
 
+**Remarks:**
+
+CSS Coverage doesn't include dynamically injected style tags without sourceURLs.
+
 </td></tr>
 <tr><td>
 
@@ -125,5 +133,9 @@ Promise that resolves to the array of coverage reports for all stylesheets.
 
 Promise that resolves to the array of coverage reports for all scripts.
 
+**Remarks:**
+
+JavaScript Coverage doesn't include anonymous scripts by default. However, scripts with sourceURLs are reported.
+
 </td></tr>
 </tbody></table>

docs/api/puppeteer.elementhandle.md

@@ -150,6 +150,25 @@ If the given function returns a promise, then this method will wait till the pro
 
 If the element is a form input, you can use [ElementHandle.autofill()](./puppeteer.elementhandle.autofill.md) to test if the form is compatible with the browser's autofill implementation. Throws an error if the form cannot be autofilled.
 
+**Remarks:**
+
+Currently, Puppeteer supports auto-filling credit card information only and in Chrome in the new headless and headful modes only.
+
+```ts
+// Select an input on the credit card form.
+const name = await page.waitForSelector('form #name');
+// Trigger autofill with the desired data.
+await name.autofill({
+  creditCard: {
+    number: '4444444444444444',
+    name: 'John Smith',
+    expiryMonth: '01',
+    expiryYear: '2030',
+    cvc: '123',
+  },
+});
+```
+
 </td></tr>
 <tr><td>
 
@@ -172,6 +191,10 @@ This method returns the bounding box of the element (relative to the main frame)
 
 This method returns boxes of the element, or `null` if the element is [not part of the layout](https://drafts.csswg.org/css-display-4/#box-generation) (example: `display: none`).
 
+**Remarks:**
+
+Boxes are represented as an array of points; Each Point is an object `{x, y}`. Box points are sorted clock-wise.
+
 </td></tr>
 <tr><td>
 
@@ -362,6 +385,12 @@ Checks if an element is visible using the same mechanism as [ElementHandle.waitF
 
 Focuses the element, and then uses [Keyboard.down()](./puppeteer.keyboard.down.md) and [Keyboard.up()](./puppeteer.keyboard.up.md).
 
+**Remarks:**
+
+If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`/`input` event will also be generated. The `text` option can be specified to force an input event to be generated.
+
+**NOTE** Modifier keys DO affect `elementHandle.press`. Holding down `Shift` will type the text in upper case.
+
 </td></tr>
 <tr><td>
 
@@ -477,6 +506,10 @@ To press a special key, like `Control` or `ArrowDown`, use [ElementHandle.press(
 
 Sets the value of an [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) to the given file paths.
 
+**Remarks:**
+
+This will not validate whether the file paths exists. Also, if a path is relative, then it is resolved against the [current working directory](https://nodejs.org/api/process.html#process_process_cwd). For locals script connecting to remote chrome environments, paths must be absolute.
+
 </td></tr>
 <tr><td>
 

docs/api/puppeteer.filechooser.md

@@ -55,6 +55,10 @@ Description
 
 Accept the file chooser request with the given file paths.
 
+**Remarks:**
+
+This will not validate whether the file paths exists. Also, if a path is relative, then it is resolved against the [current working directory](https://nodejs.org/api/process.html#process_process_cwd). For locals script connecting to remote chrome environments, paths must be absolute.
+
 </td></tr>
 <tr><td>
 

docs/api/puppeteer.frame.md

@@ -214,6 +214,17 @@ An array of child frames.
 
 Clicks the first element found that matches `selector`.
 
+**Remarks:**
+
+If `click()` triggers a navigation event and there's a separate `page.waitForNavigation()` promise to be resolved, you may end up with a race condition that yields unexpected results. The correct pattern for click and wait for navigation is the following:
+
+```ts
+const [response] = await Promise.all([
+  page.waitForNavigation(waitOptions),
+  frame.click(selector, clickOptions),
+]);
+```
+
 </td></tr>
 <tr><td>
 
@@ -278,6 +289,16 @@ Focuses the first element that matches the `selector`.
 
 Navigates the frame to the given `url`.
 
+**Remarks:**
+
+Navigation to `about:blank` or navigation to the same URL with a different hash will succeed and return `null`.
+
+:::warning
+
+Headless mode doesn't support navigation to a PDF document. See the [upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295).
+
+:::
+
 </td></tr>
 <tr><td>
 
@@ -328,6 +349,10 @@ Is `true` if the frame is an out-of-process (OOP) frame. Otherwise, `false`.
 
 Creates a locator for the provided selector. See [Locator](./puppeteer.locator.md) for details and supported actions.
 
+**Remarks:**
+
+Locators API is experimental and we will not follow semver for breaking change in the Locators API.
+
 </td></tr>
 <tr><td>
 
@@ -339,6 +364,10 @@ Creates a locator for the provided selector. See [Locator](./puppeteer.locator.m
 
 Creates a locator for the provided function. See [Locator](./puppeteer.locator.md) for details and supported actions.
 
+**Remarks:**
+
+Locators API is experimental and we will not follow semver for breaking change in the Locators API.
+
 </td></tr>
 <tr><td>
 
@@ -361,6 +390,10 @@ const element = await frame.frameElement();
 const nameOrId = await element.evaluate(frame => frame.name ?? frame.id);
 ```
 
+**Remarks:**
+
+This value is calculated once when the frame is created, and will not update if the attribute is changed later.
+
 </td></tr>
 <tr><td>
 
@@ -438,6 +471,10 @@ The frame's title.
 
 Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
 
+**Remarks:**
+
+To press a special key, like `Control` or `ArrowDown`, use [Keyboard.press()](./puppeteer.keyboard.press.md).
+
 </td></tr>
 <tr><td>
 

docs/api/puppeteer.frameaddscripttagoptions.md

@@ -87,6 +87,10 @@ string
 
 Path to a JavaScript file to be injected into the frame.
 
+**Remarks:**
+
+If `path` is a relative path, it is resolved relative to the current working directory (`process.cwd()` in Node.js).
+
 </td><td>
 
 </td></tr>

docs/api/puppeteer.frameaddstyletagoptions.md

@@ -68,6 +68,10 @@ string
 
 The path to a CSS file to be injected into the frame.
 
+**Remarks:**
+
+If `path` is a relative path, it is resolved relative to the current working directory (`process.cwd()` in Node.js).
+
 </td><td>
 
 </td></tr>

docs/api/puppeteer.httprequest.md

@@ -65,7 +65,7 @@ Description
 
 </td><td>
 
-Warning! Using this client can break Puppeteer. Use with caution.
+**_(Experimental)_** Warning! Using this client can break Puppeteer. Use with caution.
 
 </td></tr>
 </tbody></table>
@@ -95,6 +95,10 @@ Description
 
 Aborts a request.
 
+**Remarks:**
+
+To use this, request interception should be enabled with [Page.setRequestInterception()](./puppeteer.page.setrequestinterception.md). If it is not enabled, this method will throw an exception immediately.
+
 </td></tr>
 <tr><td>
 
@@ -117,6 +121,12 @@ The most recent reason for aborting the request
 
 Continues request with optional request overrides.
 
+**Remarks:**
+
+To use this, request interception should be enabled with [Page.setRequestInterception()](./puppeteer.page.setrequestinterception.md).
+
+Exception is immediately thrown if the request interception is not enabled.
+
 </td></tr>
 <tr><td>
 
@@ -150,6 +160,8 @@ Adds an async request handler to the processing queue. Deferred handlers are not
 
 Access information about the request's failure.
 
+**Remarks:**
+
 </td></tr>
 <tr><td>
 
@@ -286,6 +298,27 @@ The request's post body, if any.
 
 A `redirectChain` is a chain of requests initiated to fetch a resource.
 
+**Remarks:**
+
+`redirectChain` is shared between all the requests of the same chain.
+
+For example, if the website `http://example.com` has a single redirect to `https://example.com`, then the chain will contain one request:
+
+```ts
+const response = await page.goto('http://example.com');
+const chain = response.request().redirectChain();
+console.log(chain.length); // 1
+console.log(chain[0].url()); // 'http://example.com'
+```
+
+If the website `https://google.com` has no redirects, then the chain will be empty:
+
+```ts
+const response = await page.goto('https://google.com');
+const chain = response.request().redirectChain();
+console.log(chain.length); // 0
+```
+
 </td></tr>
 <tr><td>
 
@@ -308,6 +341,12 @@ Contains the request's resource type as it was perceived by the rendering engine
 
 Fulfills a request with the given response.
 
+**Remarks:**
+
+To use this, request interception should be enabled with [Page.setRequestInterception()](./puppeteer.page.setrequestinterception.md).
+
+Exception is immediately thrown if the request interception is not enabled.
+
 </td></tr>
 <tr><td>
 

docs/api/puppeteer.httpresponse.md

@@ -41,6 +41,10 @@ Description
 
 Promise which resolves to a buffer with response body.
 
+**Remarks:**
+
+The buffer might be re-encoded by the browser based on HTTP-headers or other heuristics. If the browser failed to detect the correct encoding, the buffer might be encoded incorrectly. See https://github.com/puppeteer/puppeteer/issues/6478.
+
 </td></tr>
 <tr><td>
 
@@ -96,6 +100,10 @@ An object with HTTP headers associated with the response. All header names are l
 
 Promise which resolves to a JSON representation of response body.
 
+**Remarks:**
+
+This method will throw if the response body is not parsable via `JSON.parse`.
+
 </td></tr>
 <tr><td>
 

docs/api/puppeteer.jshandle.md

@@ -177,6 +177,10 @@ Fetches a single property from the referenced object.
 
 A vanilla object representing the serializable portions of the referenced object.
 
+**Remarks:**
+
+If the object has a `toJSON` function, it **will not** be called.
+
 </td></tr>
 <tr><td>
 
@@ -199,5 +203,9 @@ Provides access to the [Protocol.Runtime.RemoteObject](https://chromedevtools.gi
 
 Returns a string representation of the JSHandle.
 
+**Remarks:**
+
+Useful during debugging.
+
 </td></tr>
 </tbody></table>

docs/api/puppeteer.keyboard.md

@@ -72,6 +72,14 @@ Description
 
 Dispatches a `keydown` event.
 
+**Remarks:**
+
+If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`/`input` event will also generated. The `text` option can be specified to force an input event to be generated. If `key` is a modifier key, `Shift`, `Meta`, `Control`, or `Alt`, subsequent key presses will be sent with that modifier active. To release the modifier key, use [Keyboard.up()](./puppeteer.keyboard.up.md).
+
+After the key is pressed once, subsequent calls to [Keyboard.down()](./puppeteer.keyboard.down.md) will have [repeat](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/repeat) set to true. To release the key, use [Keyboard.up()](./puppeteer.keyboard.up.md).
+
+Modifier keys DO influence [Keyboard.down()](./puppeteer.keyboard.down.md). Holding down `Shift` will type the text in upper case.
+
 </td></tr>
 <tr><td>
 
@@ -83,6 +91,12 @@ Dispatches a `keydown` event.
 
 Shortcut for [Keyboard.down()](./puppeteer.keyboard.down.md) and [Keyboard.up()](./puppeteer.keyboard.up.md).
 
+**Remarks:**
+
+If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`/`input` event will also generated. The `text` option can be specified to force an input event to be generated.
+
+Modifier keys DO effect [Keyboard.press()](./puppeteer.keyboard.press.md). Holding down `Shift` will type the text in upper case.
+
 </td></tr>
 <tr><td>
 
@@ -94,6 +108,10 @@ Shortcut for [Keyboard.down()](./puppeteer.keyboard.down.md) and [Keyboard.up()]
 
 Dispatches a `keypress` and `input` event. This does not send a `keydown` or `keyup` event.
 
+**Remarks:**
+
+Modifier keys DO NOT effect [Keyboard.sendCharacter](./puppeteer.keyboard.sendcharacter.md). Holding down `Shift` will not type the text in upper case.
+
 </td></tr>
 <tr><td>
 
@@ -105,6 +123,12 @@ Dispatches a `keypress` and `input` event. This does not send a `keydown` or `ke
 
 Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
 
+**Remarks:**
+
+To press a special key, like `Control` or `ArrowDown`, use [Keyboard.press()](./puppeteer.keyboard.press.md).
+
+Modifier keys DO NOT effect `keyboard.type`. Holding down `Shift` will not type the text in upper case.
+
 </td></tr>
 <tr><td>
 

docs/api/puppeteer.page.md

@@ -96,6 +96,16 @@ Description
 
 The Accessibility class provides methods for inspecting the browser's accessibility tree. The accessibility tree is used by assistive technology such as [screen readers](https://en.wikipedia.org/wiki/Screen_reader) or [switches](https://en.wikipedia.org/wiki/Switch_access).
 
+**Remarks:**
+
+Accessibility is a very platform-specific thing. On different platforms, there are different screen readers that might have wildly different output.
+
+Blink - Chrome's rendering engine - has a concept of "accessibility tree", which is then translated into different platform-specific APIs. Accessibility namespace gives users access to the Blink Accessibility Tree.
+
+Most of the accessibility tree gets filtered out when converting from Blink AX Tree to Platform-specific AX-Tree or by assistive technologies themselves. By default, Puppeteer tries to approximate this filtering, exposing only the "interesting" nodes of the tree.
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Accessibility` class.
+
 </td></tr>
 <tr><td>
 
@@ -113,6 +123,10 @@ The Accessibility class provides methods for inspecting the browser's accessibil
 
 The Coverage class provides methods to gather information about parts of JavaScript and CSS that were used by the page.
 
+**Remarks:**
+
+To output coverage in a form consumable by [Istanbul](https://github.com/istanbuljs), see [puppeteer-to-istanbul](https://github.com/istanbuljs/puppeteer-to-istanbul).
+
 </td></tr>
 <tr><td>
 
@@ -130,6 +144,14 @@ The Coverage class provides methods to gather information about parts of JavaScr
 
 Keyboard provides an api for managing a virtual keyboard. The high level api is [Keyboard.type()](./puppeteer.keyboard.type.md), which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page.
 
+**Remarks:**
+
+For finer control, you can use [Keyboard.down()](./puppeteer.keyboard.down.md), [Keyboard.up()](./puppeteer.keyboard.up.md), and [Keyboard.sendCharacter()](./puppeteer.keyboard.sendcharacter.md) to manually fire events as if they were generated from a real keyboard.
+
+On macOS, keyboard shortcuts like `⌘ A` -&gt; Select All do not work. See [\#1313](https://github.com/puppeteer/puppeteer/issues/1313).
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Keyboard` class.
+
 </td></tr>
 <tr><td>
 
@@ -147,6 +169,12 @@ Keyboard provides an api for managing a virtual keyboard. The high level api is
 
 The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport.
 
+**Remarks:**
+
+Every `page` object has its own Mouse, accessible with \[`page.mouse`\](\#pagemouse).
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Mouse` class.
+
 </td></tr>
 <tr><td>
 
@@ -181,6 +209,12 @@ The Touchscreen class exposes touchscreen events.
 
 The Tracing class exposes the tracing audit interface.
 
+**Remarks:**
+
+You can use `tracing.start` and `tracing.stop` to create a trace file which can be opened in Chrome DevTools or [timeline viewer](https://chromedevtools.github.io/timeline-viewer/).
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Tracing` class.
+
 </td></tr>
 </tbody></table>
 
@@ -220,6 +254,10 @@ Runs `document.querySelector` within the page. If no element matches the selecto
 
 The method runs `document.querySelectorAll` within the page. If no elements match the selector, the return value resolves to `[]`.
 
+**Remarks:**
+
+Shortcut for [Page.mainFrame().$$(selector)](./puppeteer.frame.__.md).
+
 </td></tr>
 <tr><td>
 
@@ -231,6 +269,10 @@ The method runs `document.querySelectorAll` within the page. If no elements matc
 
 This method runs `Array.from(document.querySelectorAll(selector))` within the page and passes the result as the first argument to the `pageFunction`.
 
+**Remarks:**
+
+If `pageFunction` returns a promise `$$eval` will wait for the promise to resolve and then return its value.
+
 </td></tr>
 <tr><td>
 
@@ -242,6 +284,12 @@ This method runs `Array.from(document.querySelectorAll(selector))` within the pa
 
 This method runs `document.querySelector` within the page and passes the result as the first argument to the `pageFunction`.
 
+**Remarks:**
+
+If no element is found matching `selector`, the method will throw an error.
+
+If `pageFunction` returns a promise `$eval` will wait for the promise to resolve and then return its value.
+
 </td></tr>
 <tr><td>
 
@@ -253,6 +301,10 @@ This method runs `document.querySelector` within the page and passes the result
 
 Adds a `<script>` tag into the page with the desired URL or content.
 
+**Remarks:**
+
+Shortcut for [page.mainFrame().addScriptTag(options)](./puppeteer.frame.addscripttag.md).
+
 </td></tr>
 <tr><td>
 
@@ -286,6 +338,10 @@ Shortcut for [page.mainFrame().addStyleTag(options)](./puppeteer.frame.addstylet
 
 Provide credentials for `HTTP authentication`.
 
+**Remarks:**
+
+To disable authentication, pass `null`.
+
 </td></tr>
 <tr><td>
 
@@ -330,6 +386,19 @@ Get the browser context that the page belongs to.
 
 This method fetches an element with `selector`, scrolls it into view if needed, and then uses [Page.mouse](./puppeteer.page.md#mouse) to click in the center of the element. If there's no element matching `selector`, the method throws an error.
 
+**Remarks:**
+
+Bear in mind that if `click()` triggers a navigation event and there's a separate `page.waitForNavigation()` promise to be resolved, you may end up with a race condition that yields unexpected results. The correct pattern for click and wait for navigation is the following:
+
+```ts
+const [response] = await Promise.all([
+  page.waitForNavigation(waitOptions),
+  page.click(selector, clickOptions),
+]);
+```
+
+Shortcut for [page.mainFrame().click(selector\[, options\])](./puppeteer.frame.click.md).
+
 </td></tr>
 <tr><td>
 
@@ -383,6 +452,12 @@ Creates a Chrome Devtools Protocol session attached to the page.
 
 Generates a PDF of the page with the `print` CSS media type.
 
+**Remarks:**
+
+To generate a PDF with the `screen` media type, call [\`page.emulateMediaType('screen')\`](./puppeteer.page.emulatemediatype.md) before calling `page.pdf()`.
+
+By default, `page.pdf()` generates a pdf with modified colors for printing. Use the [\`-webkit-print-color-adjust\`](https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-print-color-adjust) property to force rendering of exact colors.
+
 </td></tr>
 <tr><td>
 
@@ -405,6 +480,12 @@ Emulates a given device's metrics and user agent.
 
 To aid emulation, Puppeteer provides a list of known devices that can be via [KnownDevices](./puppeteer.knowndevices.md).
 
+**Remarks:**
+
+This method is a shortcut for calling two methods: [Page.setUserAgent()](./puppeteer.page.setuseragent.md) and [Page.setViewport()](./puppeteer.page.setviewport.md).
+
+This method will resize the page. A lot of websites don't expect phones to change size, so you should emulate before navigating to the page.
+
 </td></tr>
 <tr><td>
 
@@ -500,6 +581,14 @@ If the function passed to `page.evaluate` returns a Promise, the function will w
 
 </td><td>
 
+**Remarks:**
+
+The only difference between [page.evaluate](./puppeteer.page.evaluate.md) and `page.evaluateHandle` is that `evaluateHandle` will return the value wrapped in an in-page object.
+
+If the function passed to `page.evaluateHandle` returns a Promise, the function will wait for the promise to resolve and return its value.
+
+You can pass a string instead of a function (although functions are recommended as they are easier to debug and use with TypeScript):
+
 </td></tr>
 <tr><td>
 
@@ -547,6 +636,10 @@ Functions installed via `page.exposeFunction` survive navigations.
 
 This method fetches an element with `selector` and focuses it. If there's no element matching `selector`, the method throws an error.
 
+**Remarks:**
+
+Shortcut for [page.mainFrame().focus(selector)](./puppeteer.frame.focus.md).
+
 </td></tr>
 <tr><td>
 
@@ -580,6 +673,14 @@ Maximum time in milliseconds.
 
 This method navigate to the previous page in history.
 
+**Remarks:**
+
+The argument `options` might have the following properties:
+
+- `timeout` : Maximum navigation time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed by using the [Page.setDefaultNavigationTimeout()](./puppeteer.page.setdefaultnavigationtimeout.md) or [Page.setDefaultTimeout()](./puppeteer.page.setdefaulttimeout.md) methods.
+
+- `waitUntil` : When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:<br/> - `load` : consider navigation to be finished when the load event is fired.<br/> - `domcontentloaded` : consider navigation to be finished when the DOMContentLoaded event is fired.<br/> - `networkidle0` : consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.<br/> - `networkidle2` : consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.
+
 </td></tr>
 <tr><td>
 
@@ -591,6 +692,14 @@ This method navigate to the previous page in history.
 
 This method navigate to the next page in history.
 
+**Remarks:**
+
+The argument `options` might have the following properties:
+
+- `timeout` : Maximum navigation time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed by using the [Page.setDefaultNavigationTimeout()](./puppeteer.page.setdefaultnavigationtimeout.md) or [Page.setDefaultTimeout()](./puppeteer.page.setdefaulttimeout.md) methods.
+
+- `waitUntil`: When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:<br/> - `load` : consider navigation to be finished when the load event is fired.<br/> - `domcontentloaded` : consider navigation to be finished when the DOMContentLoaded event is fired.<br/> - `networkidle0` : consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.<br/> - `networkidle2` : consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.
+
 </td></tr>
 <tr><td>
 
@@ -602,6 +711,18 @@ This method navigate to the next page in history.
 
 Navigates the page to the given `url`.
 
+**Remarks:**
+
+Navigation to `about:blank` or navigation to the same URL with a different hash will succeed and return `null`.
+
+:::warning
+
+Headless mode doesn't support navigation to a PDF document. See the [upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295).
+
+:::
+
+Shortcut for [page.mainFrame().goto(url, options)](./puppeteer.frame.goto.md).
+
 </td></tr>
 <tr><td>
 
@@ -613,6 +734,10 @@ Navigates the page to the given `url`.
 
 This method fetches an element with `selector`, scrolls it into view if needed, and then uses [Page.mouse](./puppeteer.page.md#mouse) to hover over the center of the element. If there's no element matching `selector`, the method throws an error.
 
+**Remarks:**
+
+Shortcut for [page.mainFrame().hover(selector)](./puppeteer.page.hover.md).
+
 </td></tr>
 <tr><td>
 
@@ -674,6 +799,10 @@ We no longer support intercepting drag payloads. Use the new drag APIs found on
 
 Creates a locator for the provided selector. See [Locator](./puppeteer.locator.md) for details and supported actions.
 
+**Remarks:**
+
+Locators API is experimental and we will not follow semver for breaking change in the Locators API.
+
 </td></tr>
 <tr><td>
 
@@ -685,6 +814,10 @@ Creates a locator for the provided selector. See [Locator](./puppeteer.locator.m
 
 Creates a locator for the provided function. See [Locator](./puppeteer.locator.md) for details and supported actions.
 
+**Remarks:**
+
+Locators API is experimental and we will not follow semver for breaking change in the Locators API.
+
 </td></tr>
 <tr><td>
 
@@ -696,6 +829,10 @@ Creates a locator for the provided function. See [Locator](./puppeteer.locator.m
 
 The page's main frame.
 
+**Remarks:**
+
+Page is guaranteed to have a main frame which persists during navigations.
+
 </td></tr>
 <tr><td>
 
@@ -707,6 +844,10 @@ The page's main frame.
 
 Object containing metrics as key/value pairs.
 
+**Remarks:**
+
+All timestamps are in monotonic time: monotonically increasing time in seconds since an arbitrary point in the past.
+
 </td></tr>
 <tr><td>
 
@@ -718,6 +859,12 @@ Object containing metrics as key/value pairs.
 
 Generates a PDF of the page with the `print` CSS media type.
 
+**Remarks:**
+
+To generate a PDF with the `screen` media type, call [\`page.emulateMediaType('screen')\`](./puppeteer.page.emulatemediatype.md) before calling `page.pdf()`.
+
+By default, `page.pdf()` generates a pdf with modified colors for printing. Use the [\`-webkit-print-color-adjust\`](https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-print-color-adjust) property to force rendering of exact colors.
+
 </td></tr>
 <tr><td>
 
@@ -771,7 +918,13 @@ Removes script that injected into page by Page.evaluateOnNewDocument.
 
 </td><td>
 
-Captures a screencast of this [page](./puppeteer.page.md).
+**_(Experimental)_** Captures a screencast of this [page](./puppeteer.page.md).
+
+**Remarks:**
+
+All recordings will be [WebM](https://www.webmproject.org/) format using the [VP9](https://www.webmproject.org/vp9/) video codec. The FPS is 30.
+
+You must have [ffmpeg](https://ffmpeg.org/) installed on your system.
 
 </td></tr>
 <tr><td>
@@ -804,6 +957,10 @@ Captures a screenshot of this [page](./puppeteer.page.md).
 
 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.
 
+**Remarks:**
+
+Shortcut for [page.mainFrame().select()](./puppeteer.frame.select.md)
+
 </td></tr>
 <tr><td>
 
@@ -815,6 +972,10 @@ Triggers a `change` and `input` event once all the provided options have been se
 
 Toggles bypassing page's Content-Security-Policy.
 
+**Remarks:**
+
+NOTE: CSP bypassing happens at the moment of CSP initialization rather than evaluation. Usually, this means that `page.setBypassCSP` should be called before navigating to the domain.
+
 </td></tr>
 <tr><td>
 
@@ -848,6 +1009,14 @@ Toggles ignoring cache for each request based on the enabled state. By default,
 
 Set the content of the page.
 
+**Remarks:**
+
+The parameter `options` might have the following options.
+
+- `timeout` : Maximum time in milliseconds for resources to load, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [Page.setDefaultNavigationTimeout()](./puppeteer.page.setdefaultnavigationtimeout.md) or [Page.setDefaultTimeout()](./puppeteer.page.setdefaulttimeout.md) methods.
+
+- `waitUntil`: When to consider setting markup succeeded, defaults to `load`. Given an array of event strings, setting content is considered to be successful after all events have been fired. Events can be either:<br/> - `load` : consider setting content to be finished when the `load` event is fired.<br/> - `domcontentloaded` : consider setting content to be finished when the `DOMContentLoaded` event is fired.<br/> - `networkidle0` : consider setting content to be finished when there are no more than 0 network connections for at least `500` ms.<br/> - `networkidle2` : consider setting content to be finished when there are no more than 2 network connections for at least `500` ms.
+
 </td></tr>
 <tr><td>
 
@@ -938,6 +1107,10 @@ page.setExtraHTTPHeaders does not guarantee the order of headers in the outgoing
 
 Sets the page's geolocation.
 
+**Remarks:**
+
+Consider using [BrowserContext.overridePermissions()](./puppeteer.browsercontext.overridepermissions.md) to grant permissions for the page to read its geolocation.
+
 </td></tr>
 <tr><td>
 
@@ -947,6 +1120,10 @@ Sets the page's geolocation.
 
 </td><td>
 
+**Remarks:**
+
+NOTE: changing this value won't affect scripts that have already been run. It will take full effect on the next navigation.
+
 </td></tr>
 <tr><td>
 
@@ -997,6 +1174,10 @@ See the [Request interception guide](https://pptr.dev/guides/network-interceptio
 
 In the case of multiple pages in a single browser, each page can have its own viewport size.
 
+**Remarks:**
+
+NOTE: in certain cases, setting viewport will reload the page in order to set the isMobile or hasTouch properties.
+
 </td></tr>
 <tr><td>
 
@@ -1008,6 +1189,10 @@ In the case of multiple pages in a single browser, each page can have its own vi
 
 This method fetches an element with `selector`, scrolls it into view if needed, and then uses [Page.touchscreen](./puppeteer.page.md#touchscreen) to tap in the center of the element. If there's no element matching `selector`, the method throws an error.
 
+**Remarks:**
+
+Shortcut for [page.mainFrame().tap(selector)](./puppeteer.frame.tap.md).
+
 </td></tr>
 <tr><td>
 
@@ -1036,6 +1221,10 @@ Use [Page.createCDPSession()](./puppeteer.page.createcdpsession.md) directly.
 
 The page's title
 
+**Remarks:**
+
+Shortcut for [page.mainFrame().title()](./puppeteer.frame.title.md).
+
 </td></tr>
 <tr><td>
 
@@ -1060,6 +1249,10 @@ To press a special key, like `Control` or `ArrowDown`, use [Keyboard.press()](./
 
 The page's URL.
 
+**Remarks:**
+
+Shortcut for [page.mainFrame().url()](./puppeteer.frame.url.md).
+
 </td></tr>
 <tr><td>
 
@@ -1107,6 +1300,10 @@ This must be called before the file chooser is launched. It will not return a cu
 
 :::
 
+**Remarks:**
+
+In the "headful" browser, this method results in the native file picker dialog `not showing up` for the user.
+
 </td></tr>
 <tr><td>
 
@@ -1140,6 +1337,10 @@ Waits for the provided function, `pageFunction`, to return a truthy value when e
 
 Waits for the page to navigate to a new URL or to reload. It is useful when you run code that will indirectly cause the page to navigate.
 
+**Remarks:**
+
+Usage of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to change the URL is considered a navigation.
+
 </td></tr>
 <tr><td>
 
@@ -1160,6 +1361,12 @@ Waits for the network to be idle.
 
 </td><td>
 
+**Remarks:**
+
+Optional Waiting Parameters have:
+
+- `timeout`: 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()](./puppeteer.page.setdefaulttimeout.md) method.
+
 </td></tr>
 <tr><td>
 
@@ -1169,6 +1376,12 @@ Waits for the network to be idle.
 
 </td><td>
 
+**Remarks:**
+
+Optional Parameter have:
+
+- `timeout`: 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()](./puppeteer.page.setdefaulttimeout.md) method.
+
 </td></tr>
 <tr><td>
 
@@ -1180,6 +1393,16 @@ Waits for the network to be idle.
 
 Wait for the `selector` to appear in page. If at the moment of calling the method the `selector` already exists, the method will return immediately. If the `selector` doesn't appear after the `timeout` milliseconds of waiting, the function will throw.
 
+**Remarks:**
+
+The optional Parameter in Arguments `options` are:
+
+- `visible`: A boolean wait for element to be present in DOM and to be visible, i.e. to not have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
+
+- `hidden`: Wait for element to not be found in the DOM or to be hidden, i.e. have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
+
+- `timeout`: maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [Page.setDefaultTimeout()](./puppeteer.page.setdefaulttimeout.md) method.
+
 </td></tr>
 <tr><td>
 
@@ -1191,5 +1414,9 @@ Wait for the `selector` to appear in page. If at the moment of calling the metho
 
 All of the dedicated [WebWorkers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) associated with the page.
 
+**Remarks:**
+
+This does not contain ServiceWorkers
+
 </td></tr>
 </tbody></table>

docs/api/puppeteer.pageevent.md

@@ -52,6 +52,10 @@ Console
 
 Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`. Also emitted if the page throws an error or a warning.
 
+**Remarks:**
+
+A `console` event provides a [ConsoleMessage](./puppeteer.consolemessage.md) representing the console message that was logged.
+
 </td></tr>
 <tr><td>
 
@@ -156,6 +160,12 @@ Metrics
 
 Emitted when the JavaScript code makes a call to `console.timeStamp`. For the list of metrics see [page.metrics](./puppeteer.page.metrics.md).
 
+**Remarks:**
+
+Contains an object with two properties:
+
+- `title`: the title passed to `console.timeStamp` - `metrics`: object containing metrics as key/value pairs. The values will be `number`s.
+
 </td></tr>
 <tr><td>
 
@@ -197,6 +207,10 @@ Request
 
 Emitted when a page issues a request and contains a [HTTPRequest](./puppeteer.httprequest.md).
 
+**Remarks:**
+
+The object is readonly. See [Page.setRequestInterception()](./puppeteer.page.setrequestinterception.md) for intercepting and mutating requests.
+
 </td></tr>
 <tr><td>
 
@@ -212,6 +226,10 @@ Emitted when a request fails, for example by timing out.
 
 Contains a [HTTPRequest](./puppeteer.httprequest.md).
 
+**Remarks:**
+
+HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request will complete with `requestfinished` event and not with `requestfailed`.
+
 </td></tr>
 <tr><td>
 
@@ -238,6 +256,10 @@ RequestServedFromCache
 
 Emitted when a request ended up loading from cache. Contains a [HTTPRequest](./puppeteer.httprequest.md).
 
+**Remarks:**
+
+For certain requests, might contain undefined. [https://crbug.com/750469](https://crbug.com/750469)
+
 </td></tr>
 <tr><td>
 

docs/api/puppeteer.pdfoptions.md

@@ -89,6 +89,10 @@ HTML template for the print footer. Has the same constraints and support for spe
 
 </td><td>
 
+**Remarks:**
+
+If set, this takes priority over the `width` and `height` options.
+
 </td><td>
 
 `letter`.
@@ -219,7 +223,11 @@ boolean
 
 </td><td>
 
-Generate document outline.
+**_(Experimental)_** Generate document outline.
+
+**Remarks:**
+
+If this is enabled the PDF will also be tagged (accessible) Currently only works in old Headless (headless = 'shell') [Chromium feature request](https://issues.chromium.org/issues/41387522#comment48)
 
 </td><td>
 
@@ -263,6 +271,10 @@ string
 
 The path to save the file to.
 
+**Remarks:**
+
+If the path is relative, it's resolved relative to the current working directory.
+
 </td><td>
 
 `undefined`, which means the PDF will not be written to disk.
@@ -345,7 +357,7 @@ boolean
 
 </td><td>
 
-Generate tagged (accessible) PDF.
+**_(Experimental)_** Generate tagged (accessible) PDF.
 
 </td><td>
 

docs/api/puppeteer.puppeteernode.md

@@ -174,6 +174,10 @@ Launches a browser instance with given arguments and options when specified.
 
 When using with `puppeteer-core`, [options.executablePath](./puppeteer.launchoptions.md#executablepath) or [options.channel](./puppeteer.launchoptions.md#channel) must be provided.
 
+**Remarks:**
+
+Puppeteer can also be used to control the Chrome browser, but it works best with the version of Chrome for Testing downloaded by default. There is no guarantee it will work with any other version. If Google Chrome (rather than Chrome for Testing) is preferred, a [Chrome Canary](https://www.google.com/chrome/browser/canary.html) or [Dev Channel](https://www.chromium.org/getting-involved/dev-channel) build is suggested. See [this article](https://www.howtogeek.com/202825/what%E2%80%99s-the-difference-between-chromium-and-chrome/) for a description of the differences between Chromium and Chrome. [This article](https://chromium.googlesource.com/chromium/src/+/lkgr/docs/chromium_browser_vs_google_chrome.md) describes some differences for Linux users. See [this doc](https://developer.chrome.com/blog/chrome-for-testing/) for the description of Chrome for Testing.
+
 </td></tr>
 <tr><td>
 
@@ -185,5 +189,9 @@ When using with `puppeteer-core`, [options.executablePath](./puppeteer.launchopt
 
 Removes all non-current Firefox and Chrome binaries in the cache directory identified by the provided Puppeteer configuration. The current browser version is determined by resolving PUPPETEER_REVISIONS from Puppeteer unless `configuration.browserRevision` is provided.
 
+**Remarks:**
+
+Note that the method does not check if any other Puppeteer versions installed on the host that use the same cache directory require the non-current binaries.
+
 </td></tr>
 </tbody></table>

docs/api/puppeteer.target.md

@@ -107,6 +107,10 @@ If the target is not of type `"page"`, `"webview"` or `"background_page"`, retur
 
 Identifies what kind of target this is.
 
+**Remarks:**
+
+See [docs](https://developer.chrome.com/extensions/background_pages) for more info about background pages.
+
 </td></tr>
 <tr><td>
 

docs/api/puppeteer.touchscreen.md

@@ -63,6 +63,10 @@ Dispatches a `touchend` event.
 
 Dispatches a `touchMove` event.
 
+**Remarks:**
+
+Not every `touchMove` call results in a `touchmove` event being emitted, depending on the browser's optimizations. For example, Chrome [throttles](https://developer.chrome.com/blog/a-more-compatible-smoother-touch/#chromes-new-model-the-throttled-async-touchmove-model) touch move events.
+
 </td></tr>
 <tr><td>
 

docs/api/puppeteer.tracing.md

@@ -51,6 +51,10 @@ Description
 
 Starts a trace for the current page.
 
+**Remarks:**
+
+Only one trace can be active at a time per browser.
+
 </td></tr>
 <tr><td>
 

docs/api/puppeteer.viewport.md

@@ -49,6 +49,10 @@ number
 
 Specify device scale factor. See [devicePixelRatio](https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio) for more info.
 
+**Remarks:**
+
+Setting this value to `0` will reset this value to the system default.
+
 </td><td>
 
 `1`
@@ -89,6 +93,10 @@ number
 
 The page height in CSS pixels.
 
+**Remarks:**
+
+Setting this value to `0` will reset this value to the system default.
+
 </td><td>
 
 </td></tr>
@@ -148,6 +156,10 @@ number
 
 The page width in CSS pixels.
 
+**Remarks:**
+
+Setting this value to `0` will reset this value to the system default.
+
 </td><td>
 
 </td></tr>

docs/api/puppeteer.webworker.md

@@ -108,6 +108,14 @@ Description
 
 Evaluates a given function in the [worker](./puppeteer.webworker.md).
 
+**Remarks:**
+
+If the given function returns a promise, [evaluate](./puppeteer.webworker.evaluate.md) will wait for the promise to resolve.
+
+As a rule of thumb, if the return value of the given function is more complicated than a JSON object (e.g. most classes), then [evaluate](./puppeteer.webworker.evaluate.md) will \_likely\_ return some truncated value (or `{}`). This is because we are not returning the actual return value, but a deserialized version as a result of transferring the return value through a protocol to Puppeteer.
+
+In general, you should use [evaluateHandle](./puppeteer.webworker.evaluatehandle.md) if [evaluate](./puppeteer.webworker.evaluate.md) cannot serialize the return value properly or you need a mutable [handle](./puppeteer.jshandle.md) to the return object.
+
 </td></tr>
 <tr><td>
 
@@ -119,6 +127,12 @@ Evaluates a given function in the [worker](./puppeteer.webworker.md).
 
 Evaluates a given function in the [worker](./puppeteer.webworker.md).
 
+**Remarks:**
+
+If the given function returns a promise, [evaluate](./puppeteer.webworker.evaluate.md) will wait for the promise to resolve.
+
+In general, you should use [evaluateHandle](./puppeteer.webworker.evaluatehandle.md) if [evaluate](./puppeteer.webworker.evaluate.md) cannot serialize the return value properly or you need a mutable [handle](./puppeteer.jshandle.md) to the return object.
+
 </td></tr>
 <tr><td>
 

docs/browsers-api/index.md

@@ -73,6 +73,10 @@ Description
 
 </td><td>
 
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `InstalledBrowser` class.
+
 </td></tr>
 <tr><td>
 
@@ -87,6 +91,10 @@ Description
 
 </td><td>
 
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `TimeoutError` class.
+
 </td></tr>
 </tbody></table>
 

packages/puppeteer-core/src/common/PDFOptions.ts

@@ -168,7 +168,7 @@ export interface PDFOptions {
    * @remarks
    * If this is enabled the PDF will also be tagged (accessible)
    * Currently only works in old Headless (headless = 'shell')
-   * crbug/840455#c47
+   * {@link https://issues.chromium.org/issues/41387522#comment48 | Chromium feature request}
    *
    * @defaultValue `false`
    * @experimental

tools/docgen/src/custom_markdown_documenter.ts

@@ -1268,6 +1268,19 @@ export class MarkdownDocumenter {
       }
     }
 
+    if (apiItem instanceof ApiDocumentedItem) {
+      const isExperimental =
+        apiItem.tsdocComment?.modifierTagSet.isExperimental();
+      if (isExperimental) {
+        section.appendNodesInParagraph([
+          new DocEmphasisSpan({configuration, bold: true, italic: true}, [
+            new DocPlainText({configuration, text: '(Experimental)'}),
+          ]),
+          new DocPlainText({configuration, text: ' '}),
+        ]);
+      }
+    }
+
     if (apiItem instanceof ApiDocumentedItem) {
       if (apiItem.tsdocComment !== undefined) {
         this._appendAndMergeSection(
@@ -1291,6 +1304,21 @@ export class MarkdownDocumenter {
       }
     }
 
+    if (apiItem instanceof ApiDocumentedItem) {
+      const remarks = apiItem.tsdocComment?.remarksBlock;
+      if (remarks) {
+        section.appendNode(
+          new DocParagraph({configuration}, [
+            new DocEmphasisSpan({configuration, bold: true}, [
+              new DocPlainText({configuration, text: 'Remarks: '}),
+            ]),
+          ])
+        );
+
+        section.appendNodes(remarks.content.getChildNodes());
+      }
+    }
+
     return new DocTableCell({configuration}, section.nodes);
   }