docs(new): add TSDoc comments to BrowserFetcher (#6078)

new-docs/puppeteer.browserfetcher._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; [BrowserFetcher](./puppeteer.browserfetcher.md) &gt; [(constructor)](./puppeteer.browserfetcher._constructor_.md)
-
-## BrowserFetcher.(constructor)
-
-Constructs a new instance of the `BrowserFetcher` class
-
-<b>Signature:</b>
-
-```typescript
-constructor(projectRoot: string, options?: BrowserFetcherOptions);
-```
-
-## Parameters
-
-|  Parameter | Type | Description |
-|  --- | --- | --- |
-|  projectRoot | string |  |
-|  options | [BrowserFetcherOptions](./puppeteer.browserfetcheroptions.md) |  |
-

new-docs/puppeteer.browserfetcher._getfolderpath.md

@@ -1,24 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [BrowserFetcher](./puppeteer.browserfetcher.md) &gt; [\_getFolderPath](./puppeteer.browserfetcher._getfolderpath.md)
-
-## BrowserFetcher.\_getFolderPath() method
-
-<b>Signature:</b>
-
-```typescript
-_getFolderPath(revision: string): string;
-```
-
-## Parameters
-
-|  Parameter | Type | Description |
-|  --- | --- | --- |
-|  revision | string |  |
-
-<b>Returns:</b>
-
-string
-
-{<!-- -->string<!-- -->}
-

new-docs/puppeteer.browserfetcher.candownload.md

@@ -4,6 +4,8 @@
 
 ## BrowserFetcher.canDownload() method
 
+Initiates a HEAD request to check if the revision is available.
+
 <b>Signature:</b>
 
 ```typescript
@@ -14,9 +16,15 @@ canDownload(revision: string): Promise<boolean>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  revision | string |  |
+|  revision | string | The revision to check availability for. |
 
 <b>Returns:</b>
 
 Promise&lt;boolean&gt;
 
+A promise that resolves to `true` if the revision could be downloaded from the host.
+
+## Remarks
+
+This method is affected by the current `product`<!-- -->.
+

new-docs/puppeteer.browserfetcher.download.md

@@ -4,6 +4,8 @@
 
 ## BrowserFetcher.download() method
 
+Initiates a GET request to download the revision from the host.
+
 <b>Signature:</b>
 
 ```typescript
@@ -14,12 +16,16 @@ download(revision: string, progressCallback?: (x: number, y: number) => void): P
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  revision | string |  |
+|  revision | string | The revision to download. |
-|  progressCallback | (x: number, y: number) =&gt; void |  |
+|  progressCallback | (x: number, y: number) =&gt; void | A function that will be called with two arguments: How many bytes have been downloaded and the total number of bytes of the download. |
 
 <b>Returns:</b>
 
 Promise&lt;BrowserFetcherRevisionInfo&gt;
 
-{<!-- -->!Promise<!-- -->&lt;<!-- -->!BrowserFetcher.RevisionInfo<!-- -->&gt;<!-- -->}
+A promise with revision information when the revision is downloaded and extracted.
+
+## Remarks
+
+This method is affected by the current `product`<!-- -->.
 

new-docs/puppeteer.browserfetcher.host.md

@@ -13,3 +13,5 @@ host(): string;
 
 string
 
+The download host being used.
+

new-docs/puppeteer.browserfetcher.localrevisions.md

@@ -13,3 +13,9 @@ localRevisions(): Promise<string[]>;
 
 Promise&lt;string\[\]&gt;
 
+A promise with a list of all revision strings (for the current `product`<!-- -->) available locally on disk.
+
+## Remarks
+
+This method is affected by the current `product`<!-- -->.
+

new-docs/puppeteer.browserfetcher.md

@@ -4,25 +4,38 @@
 
 ## BrowserFetcher class
 
+BrowserFetcher can download and manage different versions of Chromium and Firefox.
+
 <b>Signature:</b>
 
 ```typescript
 export declare class BrowserFetcher 
 ```
 
-## Constructors
+## Remarks
 
-|  Constructor | Modifiers | Description |
+BrowserFetcher operates on revision strings that specify a precise version of Chromium, e.g. `"533271"`<!-- -->. Revision strings can be obtained from [omahaproxy.appspot.com](http://omahaproxy.appspot.com/)<!-- -->. In the Firefox case, BrowserFetcher downloads Firefox Nightly and operates on version numbers such as `"75"`<!-- -->.
-|  --- | --- | --- |
+
-|  [(constructor)(projectRoot, options)](./puppeteer.browserfetcher._constructor_.md) |  | Constructs a new instance of the <code>BrowserFetcher</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 `BrowserFetcher` class.
+
+## Example
+
+An example of using BrowserFetcher to download a specific version of Chromium and running Puppeteer against it:
+
+```js
+const browserFetcher = puppeteer.createBrowserFetcher();
+const revisionInfo = await browserFetcher.download('533271');
+const browser = await puppeteer.launch({executablePath: revisionInfo.executablePath})
+
+```
+\*\*NOTE\*\* BrowserFetcher is not designed to work concurrently with other instances of BrowserFetcher that share the same downloads directory.
 
 ## Methods
 
 |  Method | Modifiers | Description |
 |  --- | --- | --- |
-|  [\_getFolderPath(revision)](./puppeteer.browserfetcher._getfolderpath.md) |  |  |
+|  [canDownload(revision)](./puppeteer.browserfetcher.candownload.md) |  | Initiates a HEAD request to check if the revision is available. |
-|  [canDownload(revision)](./puppeteer.browserfetcher.candownload.md) |  |  |
+|  [download(revision, progressCallback)](./puppeteer.browserfetcher.download.md) |  | Initiates a GET request to download the revision from the host. |
-|  [download(revision, progressCallback)](./puppeteer.browserfetcher.download.md) |  |  |
 |  [host()](./puppeteer.browserfetcher.host.md) |  |  |
 |  [localRevisions()](./puppeteer.browserfetcher.localrevisions.md) |  |  |
 |  [platform()](./puppeteer.browserfetcher.platform.md) |  |  |

new-docs/puppeteer.browserfetcher.platform.md

@@ -7,9 +7,11 @@
 <b>Signature:</b>
 
 ```typescript
-platform(): string;
+platform(): Platform;
 ```
 <b>Returns:</b>
 
-string
+Platform
+
+Returns the current `Platform`<!-- -->.
 

new-docs/puppeteer.browserfetcher.product.md

@@ -7,9 +7,11 @@
 <b>Signature:</b>
 
 ```typescript
-product(): string;
+product(): Product;
 ```
 <b>Returns:</b>
 
-string
+Product
+
+Returns the current `Product`<!-- -->.
 

new-docs/puppeteer.browserfetcher.remove.md

@@ -14,9 +14,15 @@ remove(revision: string): Promise<void>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  revision | string |  |
+|  revision | string | A revision to remove for the current <code>product</code>. |
 
 <b>Returns:</b>
 
 Promise&lt;void&gt;
 
+A promise that resolves when the revision has been removes or throws if the revision has not been downloaded.
+
+## Remarks
+
+This method is affected by the current `product`<!-- -->.
+

new-docs/puppeteer.browserfetcher.revisioninfo.md

@@ -14,9 +14,11 @@ revisionInfo(revision: string): BrowserFetcherRevisionInfo;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  revision | string |  |
+|  revision | string | The revision to get info for. |
 
 <b>Returns:</b>
 
 BrowserFetcherRevisionInfo
 
+The revision info for the given revision.
+

new-docs/puppeteer.md

@@ -11,7 +11,7 @@
 |  [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) | A Browser is created when Puppeteer connects to a Chromium instance, either through [Puppeteer.launch()](./puppeteer.puppeteer.launch.md) or [Puppeteer.connect()](./puppeteer.puppeteer.connect.md)<!-- -->. |
 |  [BrowserContext](./puppeteer.browsercontext.md) | BrowserContexts provide a way to operate multiple independent browser sessions. When a browser is launched, it has a single BrowserContext used by default. The method [Browser.newPage](./puppeteer.browser.newpage.md) creates a page in the default browser context. |
-|  [BrowserFetcher](./puppeteer.browserfetcher.md) |  |
+|  [BrowserFetcher](./puppeteer.browserfetcher.md) | BrowserFetcher can download and manage different versions of Chromium and Firefox. |
 |  [CDPSession](./puppeteer.cdpsession.md) | The <code>CDPSession</code> instances are used to talk raw Chrome Devtools Protocol. |
 |  [Connection](./puppeteer.connection.md) |  |
 |  [ConsoleMessage](./puppeteer.consolemessage.md) | ConsoleMessage objects are dispatched by page via the 'console' event. |

src/node/BrowserFetcher.ts

@@ -59,7 +59,13 @@ const browserConfig = {
   },
 } as const;
 
+/**
+ * Supported platforms.
+ */
 type Platform = 'linux' | 'mac' | 'win32' | 'win64';
+/**
+ * Supported products.
+ */
 type Product = 'chrome' | 'firefox';
 
 function archiveName(
@@ -80,11 +86,7 @@ function archiveName(
 }
 
 /**
- * @param {string} product
+ * @internal
- * @param {string} platform
- * @param {string} host
- * @param {string} revision
- * @returns {string}
  */
 function downloadURL(
   product: Product,
@@ -101,7 +103,10 @@ function downloadURL(
   return url;
 }
 
-function handleArm64() {
+/**
+ * @internal
+ */
+function handleArm64(): void {
   fs.stat('/usr/bin/chromium-browser', function (err, stats) {
     if (stats === undefined) {
       console.error(`The chromium binary is not available for arm64: `);
@@ -138,6 +143,27 @@ interface BrowserFetcherRevisionInfo {
   product: string;
 }
 /**
+ * BrowserFetcher can download and manage different versions of Chromium and Firefox.
+ *
+ * @remarks
+ * BrowserFetcher operates on revision strings that specify a precise version of Chromium, e.g. `"533271"`. Revision strings can be obtained from {@link http://omahaproxy.appspot.com/ | omahaproxy.appspot.com}.
+ * In the Firefox case, BrowserFetcher downloads Firefox Nightly and
+ * operates on version numbers such as `"75"`.
+ *
+ * @example
+ * An example of using BrowserFetcher to download a specific version of Chromium
+ * and running Puppeteer against it:
+ *
+ * ```js
+ * const browserFetcher = puppeteer.createBrowserFetcher();
+ * const revisionInfo = await browserFetcher.download('533271');
+ * const browser = await puppeteer.launch({executablePath: revisionInfo.executablePath})
+ * ```
+ *
+ * **NOTE** BrowserFetcher is not designed to work concurrently with other
+ * instances of BrowserFetcher that share the same downloads directory.
+ *
+ * @public
  */
 
 export class BrowserFetcher {
@@ -146,6 +172,9 @@ export class BrowserFetcher {
   private _downloadHost: string;
   private _platform: Platform;
 
+  /**
+   * @internal
+   */
   constructor(projectRoot: string, options: BrowserFetcherOptions = {}) {
     this._product = (options.product || 'chrome').toLowerCase() as Product;
     assert(
@@ -178,18 +207,35 @@ export class BrowserFetcher {
     else assert(this._platform, 'Unsupported platform: ' + os.platform());
   }
 
-  platform(): string {
+  /**
+   * @returns Returns the current `Platform`.
+   */
+  platform(): Platform {
     return this._platform;
   }
 
-  product(): string {
+  /**
+   * @returns Returns the current `Product`.
+   */
+  product(): Product {
     return this._product;
   }
 
+  /**
+   * @returns The download host being used.
+   */
   host(): string {
     return this._downloadHost;
   }
 
+  /**
+   * Initiates a HEAD request to check if the revision is available.
+   * @remarks
+   * This method is affected by the current `product`.
+   * @param revision - The revision to check availability for.
+   * @returns A promise that resolves to `true` if the revision could be downloaded
+   * from the host.
+   */
   canDownload(revision: string): Promise<boolean> {
     const url = downloadURL(
       this._product,
@@ -209,9 +255,14 @@ export class BrowserFetcher {
   }
 
   /**
-   * @param {string} revision
+   * Initiates a GET request to download the revision from the host.
-   * @param {?function(number, number):void} progressCallback
+   * @remarks
-   * @returns {!Promise<!BrowserFetcher.RevisionInfo>}
+   * This method is affected by the current `product`.
+   * @param revision - The revision to download.
+   * @param progressCallback - A function that will be called with two arguments:
+   * How many bytes have been downloaded and the total number of bytes of the download.
+   * @returns A promise with revision information when the revision is downloaded
+   * and extracted.
    */
   async download(
     revision: string,
@@ -244,6 +295,12 @@ export class BrowserFetcher {
     return revisionInfo;
   }
 
+  /**
+   * @remarks
+   * This method is affected by the current `product`.
+   * @returns A promise with a list of all revision strings (for the current `product`)
+   * available locally on disk.
+   */
   async localRevisions(): Promise<string[]> {
     if (!(await existsAsync(this._downloadsFolder))) return [];
     const fileNames = await readdirAsync(this._downloadsFolder);
@@ -253,6 +310,13 @@ export class BrowserFetcher {
       .map((entry) => entry.revision);
   }
 
+  /**
+   * @remarks
+   * This method is affected by the current `product`.
+   * @param revision - A revision to remove for the current `product`.
+   * @returns A promise that resolves when the revision has been removes or
+   * throws if the revision has not been downloaded.
+   */
   async remove(revision: string): Promise<void> {
     const folderPath = this._getFolderPath(revision);
     assert(
@@ -262,6 +326,10 @@ export class BrowserFetcher {
     await new Promise((fulfill) => removeRecursive(folderPath, fulfill));
   }
 
+  /**
+   * @param revision - The revision to get info for.
+   * @returns The revision info for the given revision.
+   */
   revisionInfo(revision: string): BrowserFetcherRevisionInfo {
     const folderPath = this._getFolderPath(revision);
     let executablePath = '';
@@ -331,8 +399,7 @@ export class BrowserFetcher {
   }
 
   /**
-   * @param {string} revision
+   * @internal
-   * @returns {string}
    */
   _getFolderPath(revision: string): string {
     return path.join(this._downloadsFolder, this._platform + '-' + revision);
@@ -352,10 +419,7 @@ function parseFolderPath(
 }
 
 /**
- * @param {string} url
+ * @internal
- * @param {string} destinationPath
- * @param {?function(number, number):void} progressCallback
- * @returns {!Promise}
  */
 function downloadFile(
   url: string,
@@ -415,9 +479,7 @@ function install(archivePath: string, folderPath: string): Promise<unknown> {
 }
 
 /**
- * @param {string} tarPath
+ * @internal
- * @param {string} folderPath
- * @returns {!Promise<?Error>}
  */
 function extractTar(tarPath: string, folderPath: string): Promise<unknown> {
   // eslint-disable-next-line @typescript-eslint/no-var-requires
@@ -434,11 +496,7 @@ function extractTar(tarPath: string, folderPath: string): Promise<unknown> {
 }
 
 /**
- * Install *.app directory from dmg file
+ * @internal
- *
- * @param {string} dmgPath
- * @param {string} folderPath
- * @returns {!Promise<?Error>}
  */
 function installDMG(dmgPath: string, folderPath: string): Promise<void> {
   let mountPath;