feat(new-docs): add TSDoc comments to Accessibility (#5971)

* feat(new-docs): add tsdoc to `Accessibility`

new-docs/puppeteer.accessibility._constructor_.md

@@ -1,20 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Accessibility](./puppeteer.accessibility.md) &gt; [(constructor)](./puppeteer.accessibility._constructor_.md)
-
-## Accessibility.(constructor)
-
-Constructs a new instance of the `Accessibility` class
-
-<b>Signature:</b>
-
-```typescript
-constructor(client: CDPSession);
-```
-
-## Parameters
-
-|  Parameter | Type | Description |
-|  --- | --- | --- |
-|  client | [CDPSession](./puppeteer.cdpsession.md) |  |
-

new-docs/puppeteer.accessibility.md

@@ -4,21 +4,27 @@
 
 ## Accessibility class
 
+The Accessibility class provides methods for inspecting Chromium'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)<!-- -->.
+
 <b>Signature:</b>
 
 ```typescript
 export declare class Accessibility 
 ```
 
-## Constructors
+## Remarks
 
-|  Constructor | Modifiers | Description |
+Accessibility is a very platform-specific thing. On different platforms, there are different screen readers that might have wildly different output.
-|  --- | --- | --- |
+
-|  [(constructor)(client)](./puppeteer.accessibility._constructor_.md) |  | Constructs a new instance of the <code>Accessibility</code> class |
+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.
 
 ## Methods
 
 |  Method | Modifiers | Description |
 |  --- | --- | --- |
-|  [snapshot(options)](./puppeteer.accessibility.snapshot.md) |  |  |
+|  [snapshot(options)](./puppeteer.accessibility.snapshot.md) |  | Captures the current state of the accessibility tree. The returned object represents the root accessible node of the page. |
 

new-docs/puppeteer.accessibility.snapshot.md

@@ -4,22 +4,58 @@
 
 ## Accessibility.snapshot() method
 
+Captures the current state of the accessibility tree. The returned object represents the root accessible node of the page.
+
 <b>Signature:</b>
 
 ```typescript
-snapshot(options?: {
+snapshot(options?: SnapshotOptions): Promise<SerializedAXNode>;
-        interestingOnly?: boolean;
-        root?: ElementHandle;
-    }): Promise<SerializedAXNode>;
 ```
 
 ## Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  options | { interestingOnly?: boolean; root?: [ElementHandle](./puppeteer.elementhandle.md)<!-- -->; } |  |
+|  options | [SnapshotOptions](./puppeteer.snapshotoptions.md) |  |
 
 <b>Returns:</b>
 
-Promise&lt;SerializedAXNode&gt;
+Promise&lt;[SerializedAXNode](./puppeteer.serializedaxnode.md)<!-- -->&gt;
+
+An AXNode object represeting the snapshot.
+
+## Remarks
+
+\*\*NOTE\*\* The Chromium 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`<!-- -->.
+
+## Example 1
+
+An example of dumping the entire accessibility tree:
+
+```js
+const snapshot = await page.accessibility.snapshot();
+console.log(snapshot);
+
+```
+
+## Example 2
+
+An example of logging the focused node's name:
+
+```js
+const snapshot = await page.accessibility.snapshot();
+const node = findFocusedNode(snapshot);
+console.log(node && node.name);
+
+function findFocusedNode(node) {
+  if (node.focused)
+    return node;
+  for (const child of node.children || []) {
+    const foundNode = findFocusedNode(child);
+    return foundNode;
+  }
+  return null;
+}
+
+```
 

new-docs/puppeteer.md

@@ -8,7 +8,7 @@
 
 |  Class | Description |
 |  --- | --- |
-|  [Accessibility](./puppeteer.accessibility.md) |  |
+|  [Accessibility](./puppeteer.accessibility.md) | The Accessibility class provides methods for inspecting Chromium'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)<!-- -->. |
 |  [Browser](./puppeteer.browser.md) |  |
 |  [BrowserContext](./puppeteer.browsercontext.md) |  |
 |  [BrowserFetcher](./puppeteer.browserfetcher.md) |  |
@@ -53,6 +53,8 @@
 |  Interface | Description |
 |  --- | --- |
 |  [BrowserFetcherOptions](./puppeteer.browserfetcheroptions.md) |  |
+|  [SerializedAXNode](./puppeteer.serializedaxnode.md) | Represents a Node and the properties of it that are relevant to Accessibility. |
+|  [SnapshotOptions](./puppeteer.snapshotoptions.md) |  |
 
 ## Variables
 

new-docs/puppeteer.serializedaxnode.autocomplete.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [autocomplete](./puppeteer.serializedaxnode.autocomplete.md)
+
+## SerializedAXNode.autocomplete property
+
+<b>Signature:</b>
+
+```typescript
+autocomplete?: string;
+```

new-docs/puppeteer.serializedaxnode.checked.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [checked](./puppeteer.serializedaxnode.checked.md)
+
+## SerializedAXNode.checked property
+
+Whether the checkbox is checked, or in a [mixed state](https://www.w3.org/TR/wai-aria-practices/examples/checkbox/checkbox-2/checkbox-2.html)<!-- -->.
+
+<b>Signature:</b>
+
+```typescript
+checked?: boolean | 'mixed';
+```

new-docs/puppeteer.serializedaxnode.children.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [children](./puppeteer.serializedaxnode.children.md)
+
+## SerializedAXNode.children property
+
+Children of this node, if there are any.
+
+<b>Signature:</b>
+
+```typescript
+children?: SerializedAXNode[];
+```

new-docs/puppeteer.serializedaxnode.description.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [description](./puppeteer.serializedaxnode.description.md)
+
+## SerializedAXNode.description property
+
+An additional human readable description of the node.
+
+<b>Signature:</b>
+
+```typescript
+description?: string;
+```

new-docs/puppeteer.serializedaxnode.disabled.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [disabled](./puppeteer.serializedaxnode.disabled.md)
+
+## SerializedAXNode.disabled property
+
+<b>Signature:</b>
+
+```typescript
+disabled?: boolean;
+```

new-docs/puppeteer.serializedaxnode.expanded.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [expanded](./puppeteer.serializedaxnode.expanded.md)
+
+## SerializedAXNode.expanded property
+
+<b>Signature:</b>
+
+```typescript
+expanded?: boolean;
+```

new-docs/puppeteer.serializedaxnode.focused.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [focused](./puppeteer.serializedaxnode.focused.md)
+
+## SerializedAXNode.focused property
+
+<b>Signature:</b>
+
+```typescript
+focused?: boolean;
+```

new-docs/puppeteer.serializedaxnode.haspopup.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [haspopup](./puppeteer.serializedaxnode.haspopup.md)
+
+## SerializedAXNode.haspopup property
+
+<b>Signature:</b>
+
+```typescript
+haspopup?: string;
+```

new-docs/puppeteer.serializedaxnode.invalid.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [invalid](./puppeteer.serializedaxnode.invalid.md)
+
+## SerializedAXNode.invalid property
+
+Whether and in what way this node's value is invalid.
+
+<b>Signature:</b>
+
+```typescript
+invalid?: string;
+```

new-docs/puppeteer.serializedaxnode.keyshortcuts.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [keyshortcuts](./puppeteer.serializedaxnode.keyshortcuts.md)
+
+## SerializedAXNode.keyshortcuts property
+
+Any keyboard shortcuts associated with this node.
+
+<b>Signature:</b>
+
+```typescript
+keyshortcuts?: string;
+```

new-docs/puppeteer.serializedaxnode.level.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [level](./puppeteer.serializedaxnode.level.md)
+
+## SerializedAXNode.level property
+
+The level of a heading.
+
+<b>Signature:</b>
+
+```typescript
+level?: number;
+```

new-docs/puppeteer.serializedaxnode.md

@@ -0,0 +1,45 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [SerializedAXNode](./puppeteer.serializedaxnode.md)
+
+## SerializedAXNode interface
+
+Represents a Node and the properties of it that are relevant to Accessibility.
+
+<b>Signature:</b>
+
+```typescript
+export interface SerializedAXNode 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [autocomplete](./puppeteer.serializedaxnode.autocomplete.md) | string |  |
+|  [checked](./puppeteer.serializedaxnode.checked.md) | boolean \| 'mixed' | Whether the checkbox is checked, or in a [mixed state](https://www.w3.org/TR/wai-aria-practices/examples/checkbox/checkbox-2/checkbox-2.html)<!-- -->. |
+|  [children](./puppeteer.serializedaxnode.children.md) | [SerializedAXNode](./puppeteer.serializedaxnode.md)<!-- -->\[\] | Children of this node, if there are any. |
+|  [description](./puppeteer.serializedaxnode.description.md) | string | An additional human readable description of the node. |
+|  [disabled](./puppeteer.serializedaxnode.disabled.md) | boolean |  |
+|  [expanded](./puppeteer.serializedaxnode.expanded.md) | boolean |  |
+|  [focused](./puppeteer.serializedaxnode.focused.md) | boolean |  |
+|  [haspopup](./puppeteer.serializedaxnode.haspopup.md) | string |  |
+|  [invalid](./puppeteer.serializedaxnode.invalid.md) | string | Whether and in what way this node's value is invalid. |
+|  [keyshortcuts](./puppeteer.serializedaxnode.keyshortcuts.md) | string | Any keyboard shortcuts associated with this node. |
+|  [level](./puppeteer.serializedaxnode.level.md) | number | The level of a heading. |
+|  [modal](./puppeteer.serializedaxnode.modal.md) | boolean |  |
+|  [multiline](./puppeteer.serializedaxnode.multiline.md) | boolean |  |
+|  [multiselectable](./puppeteer.serializedaxnode.multiselectable.md) | boolean | Whether more than one child can be selected. |
+|  [name](./puppeteer.serializedaxnode.name.md) | string | A human readable name for the node. |
+|  [orientation](./puppeteer.serializedaxnode.orientation.md) | string |  |
+|  [pressed](./puppeteer.serializedaxnode.pressed.md) | boolean \| 'mixed' | Whether the node is checked or in a mixed state. |
+|  [readonly](./puppeteer.serializedaxnode.readonly.md) | boolean |  |
+|  [required](./puppeteer.serializedaxnode.required.md) | boolean |  |
+|  [role](./puppeteer.serializedaxnode.role.md) | string | The [role](https://www.w3.org/TR/wai-aria/#usage_intro) of the node. |
+|  [roledescription](./puppeteer.serializedaxnode.roledescription.md) | string | A human readable alternative to the role. |
+|  [selected](./puppeteer.serializedaxnode.selected.md) | boolean |  |
+|  [value](./puppeteer.serializedaxnode.value.md) | string \| number | The current value of the node. |
+|  [valuemax](./puppeteer.serializedaxnode.valuemax.md) | number |  |
+|  [valuemin](./puppeteer.serializedaxnode.valuemin.md) | number |  |
+|  [valuetext](./puppeteer.serializedaxnode.valuetext.md) | string | A description of the current value. |
+

new-docs/puppeteer.serializedaxnode.modal.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [modal](./puppeteer.serializedaxnode.modal.md)
+
+## SerializedAXNode.modal property
+
+<b>Signature:</b>
+
+```typescript
+modal?: boolean;
+```

new-docs/puppeteer.serializedaxnode.multiline.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [multiline](./puppeteer.serializedaxnode.multiline.md)
+
+## SerializedAXNode.multiline property
+
+<b>Signature:</b>
+
+```typescript
+multiline?: boolean;
+```

new-docs/puppeteer.serializedaxnode.multiselectable.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [multiselectable](./puppeteer.serializedaxnode.multiselectable.md)
+
+## SerializedAXNode.multiselectable property
+
+Whether more than one child can be selected.
+
+<b>Signature:</b>
+
+```typescript
+multiselectable?: boolean;
+```

new-docs/puppeteer.serializedaxnode.name.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [name](./puppeteer.serializedaxnode.name.md)
+
+## SerializedAXNode.name property
+
+A human readable name for the node.
+
+<b>Signature:</b>
+
+```typescript
+name?: string;
+```

new-docs/puppeteer.serializedaxnode.orientation.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [orientation](./puppeteer.serializedaxnode.orientation.md)
+
+## SerializedAXNode.orientation property
+
+<b>Signature:</b>
+
+```typescript
+orientation?: string;
+```

new-docs/puppeteer.serializedaxnode.pressed.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [pressed](./puppeteer.serializedaxnode.pressed.md)
+
+## SerializedAXNode.pressed property
+
+Whether the node is checked or in a mixed state.
+
+<b>Signature:</b>
+
+```typescript
+pressed?: boolean | 'mixed';
+```

new-docs/puppeteer.serializedaxnode.readonly.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [readonly](./puppeteer.serializedaxnode.readonly.md)
+
+## SerializedAXNode.readonly property
+
+<b>Signature:</b>
+
+```typescript
+readonly?: boolean;
+```

new-docs/puppeteer.serializedaxnode.required.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [required](./puppeteer.serializedaxnode.required.md)
+
+## SerializedAXNode.required property
+
+<b>Signature:</b>
+
+```typescript
+required?: boolean;
+```

new-docs/puppeteer.serializedaxnode.role.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [role](./puppeteer.serializedaxnode.role.md)
+
+## SerializedAXNode.role property
+
+The [role](https://www.w3.org/TR/wai-aria/#usage_intro) of the node.
+
+<b>Signature:</b>
+
+```typescript
+role: string;
+```

new-docs/puppeteer.serializedaxnode.roledescription.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [roledescription](./puppeteer.serializedaxnode.roledescription.md)
+
+## SerializedAXNode.roledescription property
+
+A human readable alternative to the role.
+
+<b>Signature:</b>
+
+```typescript
+roledescription?: string;
+```

new-docs/puppeteer.serializedaxnode.selected.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [selected](./puppeteer.serializedaxnode.selected.md)
+
+## SerializedAXNode.selected property
+
+<b>Signature:</b>
+
+```typescript
+selected?: boolean;
+```

new-docs/puppeteer.serializedaxnode.value.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [value](./puppeteer.serializedaxnode.value.md)
+
+## SerializedAXNode.value property
+
+The current value of the node.
+
+<b>Signature:</b>
+
+```typescript
+value?: string | number;
+```

new-docs/puppeteer.serializedaxnode.valuemax.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [valuemax](./puppeteer.serializedaxnode.valuemax.md)
+
+## SerializedAXNode.valuemax property
+
+<b>Signature:</b>
+
+```typescript
+valuemax?: number;
+```

new-docs/puppeteer.serializedaxnode.valuemin.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [valuemin](./puppeteer.serializedaxnode.valuemin.md)
+
+## SerializedAXNode.valuemin property
+
+<b>Signature:</b>
+
+```typescript
+valuemin?: number;
+```

new-docs/puppeteer.serializedaxnode.valuetext.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; [SerializedAXNode](./puppeteer.serializedaxnode.md) &gt; [valuetext](./puppeteer.serializedaxnode.valuetext.md)
+
+## SerializedAXNode.valuetext property
+
+A description of the current value.
+
+<b>Signature:</b>
+
+```typescript
+valuetext?: string;
+```

new-docs/puppeteer.snapshotoptions.interestingonly.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; [SnapshotOptions](./puppeteer.snapshotoptions.md) &gt; [interestingOnly](./puppeteer.snapshotoptions.interestingonly.md)
+
+## SnapshotOptions.interestingOnly property
+
+Prune unintersting nodes from the tree.
+
+<b>Signature:</b>
+
+```typescript
+interestingOnly?: boolean;
+```

new-docs/puppeteer.snapshotoptions.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; [SnapshotOptions](./puppeteer.snapshotoptions.md)
+
+## SnapshotOptions interface
+
+
+<b>Signature:</b>
+
+```typescript
+export interface SnapshotOptions 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [interestingOnly](./puppeteer.snapshotoptions.interestingonly.md) | boolean | Prune unintersting nodes from the tree. |
+|  [root](./puppeteer.snapshotoptions.root.md) | [ElementHandle](./puppeteer.elementhandle.md) | Prune unintersting nodes from the tree. |
+

new-docs/puppeteer.snapshotoptions.root.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; [SnapshotOptions](./puppeteer.snapshotoptions.md) &gt; [root](./puppeteer.snapshotoptions.root.md)
+
+## SnapshotOptions.root property
+
+Prune unintersting nodes from the tree.
+
+<b>Signature:</b>
+
+```typescript
+root?: ElementHandle;
+```

src/Accessibility.ts

@@ -18,44 +18,166 @@ import { CDPSession } from './Connection';
 import { ElementHandle } from './JSHandle';
 import Protocol from './protocol';
 
-interface SerializedAXNode {
+/**
+ * Represents a Node and the properties of it that are relevant to Accessibility.
+ * @public
+ */
+export interface SerializedAXNode {
+  /**
+   * The {@link https://www.w3.org/TR/wai-aria/#usage_intro | role} of the node.
+   */
   role: string;
+  /**
+   * A human readable name for the node.
+   */
   name?: string;
+  /**
+   * The current value of the node.
+   */
   value?: string | number;
+  /**
+   * An additional human readable description of the node.
+   */
   description?: string;
+  /**
+   * Any keyboard shortcuts associated with this node.
+   */
   keyshortcuts?: string;
+  /**
+   * A human readable alternative to the role.
+   */
   roledescription?: string;
+  /**
+   * A description of the current value.
+   */
   valuetext?: string;
   disabled?: boolean;
   expanded?: boolean;
   focused?: boolean;
   modal?: boolean;
   multiline?: boolean;
+  /**
+   * Whether more than one child can be selected.
+   */
   multiselectable?: boolean;
   readonly?: boolean;
   required?: boolean;
   selected?: boolean;
+  /**
+   * Whether the checkbox is checked, or in a {@link https://www.w3.org/TR/wai-aria-practices/examples/checkbox/checkbox-2/checkbox-2.html | mixed state}.
+   */
   checked?: boolean | 'mixed';
+  /**
+   * Whether the node is checked or in a mixed state.
+   */
   pressed?: boolean | 'mixed';
+  /**
+   * The level of a heading.
+   */
   level?: number;
   valuemin?: number;
   valuemax?: number;
   autocomplete?: string;
   haspopup?: string;
+  /**
+   * Whether and in what way this node's value is invalid.
+   */
   invalid?: string;
   orientation?: string;
+  /**
+   * Children of this node, if there are any.
+   */
   children?: SerializedAXNode[];
 }
 
+/**
+ * @public
+ */
+export interface SnapshotOptions {
+  /**
+   * Prune unintersting nodes from the tree.
+   * @defaultValue true
+   */
+  interestingOnly?: boolean;
+  /**
+   * Prune unintersting nodes from the tree.
+   * @defaultValue The root node of the entire page.
+   */
+  root?: ElementHandle;
+}
+
+/**
+ * The Accessibility class provides methods for inspecting Chromium's
+ * accessibility tree. The accessibility tree is used by assistive technology
+ * such as {@link https://en.wikipedia.org/wiki/Screen_reader | screen readers} or
+ * {@link https://en.wikipedia.org/wiki/Switch_access | switches}.
+ *
+ * @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.
+ *
+ * @public
+ */
 export class Accessibility {
   private _client: CDPSession;
 
+  /**
+   * @internal
+   */
   constructor(client: CDPSession) {
     this._client = client;
   }
 
+  /**
+   * Captures the current state of the accessibility tree.
+   * The returned object represents the root accessible node of the page.
+   *
+   * @remarks
+   *
+   * **NOTE** The Chromium 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`.
+   *
+   * @example
+   * An example of dumping the entire accessibility tree:
+   * ```js
+   * const snapshot = await page.accessibility.snapshot();
+   * console.log(snapshot);
+   * ```
+   *
+   * @example
+   * An example of logging the focused node's name:
+   * ```js
+   * const snapshot = await page.accessibility.snapshot();
+   * const node = findFocusedNode(snapshot);
+   * console.log(node && node.name);
+   *
+   * function findFocusedNode(node) {
+   *   if (node.focused)
+   *     return node;
+   *   for (const child of node.children || []) {
+   *     const foundNode = findFocusedNode(child);
+   *     return foundNode;
+   *   }
+   *   return null;
+   * }
+   * ```
+   *
+   * @returns An AXNode object represeting the snapshot.
+   *
+   */
   public async snapshot(
-    options: { interestingOnly?: boolean; root?: ElementHandle } = {}
+    options: SnapshotOptions = {}
   ): Promise<SerializedAXNode> {
     const { interestingOnly = true, root = null } = options;
     const { nodes } = await this._client.send('Accessibility.getFullAXTree');

utils/doclint/check_public_api/index.js

@@ -612,6 +612,13 @@ function compareDocumentations(actual, expected) {
           expectedName: 'VisionDeficiency',
         },
       ],
+      [
+        'Method Accessibility.snapshot() options',
+        {
+          actualName: 'Object',
+          expectedName: 'SnapshotOptions',
+        },
+      ],
     ]);
 
     const expectedForSource = expectedNamingMismatches.get(source);