docs(new): migrate FileChooser docs to TSDoc (#6092)

Co-authored-by: martinsplitt <martin@geekonaut.de>

new-docs/puppeteer.filechooser._constructor_.md

@@ -1,21 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [FileChooser](./puppeteer.filechooser.md) &gt; [(constructor)](./puppeteer.filechooser._constructor_.md)
-
-## FileChooser.(constructor)
-
-Constructs a new instance of the `FileChooser` class
-
-<b>Signature:</b>
-
-```typescript
-constructor(element: ElementHandle, event: Protocol.Page.fileChooserOpenedPayload);
-```
-
-## Parameters
-
-|  Parameter | Type | Description |
-|  --- | --- | --- |
-|  element | [ElementHandle](./puppeteer.elementhandle.md) |  |
-|  event | Protocol.Page.fileChooserOpenedPayload |  |
-

new-docs/puppeteer.filechooser.accept.md

@@ -4,6 +4,8 @@
 
 ## FileChooser.accept() method
 
+Accept the file chooser request with given paths.
+
 <b>Signature:</b>
 
 ```typescript
@@ -14,7 +16,7 @@ accept(filePaths: string[]): Promise<void>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  filePaths | string\[\] |  |
+|  filePaths | string\[\] | If some of the <code>filePaths</code> are relative paths, then they are resolved relative to the [current working directory](https://nodejs.org/api/process.html#process_process_cwd)<!-- -->. |
 
 <b>Returns:</b>
 

new-docs/puppeteer.filechooser.cancel.md

@@ -4,6 +4,8 @@
 
 ## FileChooser.cancel() method
 
+Closes the file chooser without selecting any files.
+
 <b>Signature:</b>
 
 ```typescript

new-docs/puppeteer.filechooser.ismultiple.md

@@ -4,6 +4,8 @@
 
 ## FileChooser.isMultiple() method
 
+Whether file chooser allow for [multiple](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#attr-multiple) file selection.
+
 <b>Signature:</b>
 
 ```typescript

new-docs/puppeteer.filechooser.md

@@ -4,23 +4,39 @@
 
 ## FileChooser class
 
+File choosers let you react to the page requesting for a file.
+
 <b>Signature:</b>
 
 ```typescript
 export declare class FileChooser 
 ```
 
-## Constructors
+## Remarks
 
-|  Constructor | Modifiers | Description |
+`FileChooser` objects are returned via the `page.waitForFileChooser` method.
-|  --- | --- | --- |
+
-|  [(constructor)(element, event)](./puppeteer.filechooser._constructor_.md) |  | Constructs a new instance of the <code>FileChooser</code> class |
+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.
+
+## Example
+
+An example of using `FileChooser`<!-- -->:
+
+```js
+const [fileChooser] = await Promise.all([
+  page.waitForFileChooser(),
+  page.click('#upload-file-button'), // some button that triggers file selection
+]);
+await fileChooser.accept(['/tmp/myfile.pdf']);
+
+```
+\*\*NOTE\*\* 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.
 
 ## Methods
 
 |  Method | Modifiers | Description |
 |  --- | --- | --- |
-|  [accept(filePaths)](./puppeteer.filechooser.accept.md) |  |  |
+|  [accept(filePaths)](./puppeteer.filechooser.accept.md) |  | Accept the file chooser request with given paths. |
-|  [cancel()](./puppeteer.filechooser.cancel.md) |  |  |
+|  [cancel()](./puppeteer.filechooser.cancel.md) |  | Closes the file chooser without selecting any files. |
-|  [isMultiple()](./puppeteer.filechooser.ismultiple.md) |  |  |
+|  [isMultiple()](./puppeteer.filechooser.ismultiple.md) |  | Whether file chooser allow for [multiple](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#attr-multiple) file selection. |
 

new-docs/puppeteer.md

@@ -20,7 +20,7 @@
 |  [ElementHandle](./puppeteer.elementhandle.md) | ElementHandle represents an in-page DOM element. |
 |  [EventEmitter](./puppeteer.eventemitter.md) | The EventEmitter class that many Puppeteer classes extend. |
 |  [ExecutionContext](./puppeteer.executioncontext.md) |  |
-|  [FileChooser](./puppeteer.filechooser.md) |  |
+|  [FileChooser](./puppeteer.filechooser.md) | File choosers let you react to the page requesting for a file. |
 |  [Frame](./puppeteer.frame.md) |  |
 |  [FrameManager](./puppeteer.framemanager.md) |  |
 |  [HTTPRequest](./puppeteer.httprequest.md) |  |

src/common/FileChooser.ts

@@ -18,11 +18,31 @@ import { ElementHandle } from './JSHandle';
 import Protocol from '../protocol';
 import { assert } from './assert';
 
+/**
+ * File choosers let you react to the page requesting for a file.
+ * @remarks
+ * `FileChooser` objects are returned via the `page.waitForFileChooser` method.
+ * @example
+ * An example of using `FileChooser`:
+ * ```js
+ * const [fileChooser] = await Promise.all([
+ *   page.waitForFileChooser(),
+ *   page.click('#upload-file-button'), // some button that triggers file selection
+ * ]);
+ * await fileChooser.accept(['/tmp/myfile.pdf']);
+ * ```
+ * **NOTE** 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.
+ */
 export class FileChooser {
   private _element: ElementHandle;
   private _multiple: boolean;
   private _handled = false;
 
+  /**
+   * @internal
+   */
   constructor(
     element: ElementHandle,
     event: Protocol.Page.fileChooserOpenedPayload
@@ -31,10 +51,18 @@ export class FileChooser {
     this._multiple = event.mode !== 'selectSingle';
   }
 
+  /**
+   * Whether file chooser allow for {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#attr-multiple | multiple} file selection.
+   */
   isMultiple(): boolean {
     return this._multiple;
   }
 
+  /**
+   * Accept the file chooser request with given paths.
+   * @param filePaths - If some of the  `filePaths` are relative paths,
+   * then they are resolved relative to the {@link https://nodejs.org/api/process.html#process_process_cwd | current working directory}.
+   */
   async accept(filePaths: string[]): Promise<void> {
     assert(
       !this._handled,
@@ -44,6 +72,9 @@ export class FileChooser {
     await this._element.uploadFile(...filePaths);
   }
 
+  /**
+   * Closes the file chooser without selecting any files.
+   */
   async cancel(): Promise<void> {
     assert(
       !this._handled,