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

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

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,