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

2024-06-14 14:02:48 +00:00 · 2020-06-24 10:33:19 +02:00 · 2020-06-24 10:33:19 +02:00 · 73b97956cc
commit 73b97956cc
parent 37f6032003
13 changed files with 148 additions and 88 deletions
--- a/new-docs/puppeteer.browserfetcher._constructor_.md
+++ b/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) |  |
-
--- a/new-docs/puppeteer.browserfetcher._getfolderpath.md
+++ b/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<!-- -->}
-
--- a/new-docs/puppeteer.browserfetcher.candownload.md
+++ b/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`<!-- -->.
+
--- a/new-docs/puppeteer.browserfetcher.download.md
+++ b/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 |  |
-|  progressCallback | (x: number, y: number) =&gt; void |  |
+|  revision | string | The revision to download. |
+|  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`<!-- -->.

--- a/new-docs/puppeteer.browserfetcher.host.md
+++ b/new-docs/puppeteer.browserfetcher.host.md
@ -13,3 +13,5 @@ host(): string;

 string

+The download host being used.
+
--- a/new-docs/puppeteer.browserfetcher.localrevisions.md
+++ b/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`<!-- -->.
+
--- a/new-docs/puppeteer.browserfetcher.md
+++ b/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 |
-|  --- | --- | --- |
-|  [(constructor)(projectRoot, options)](./puppeteer.browserfetcher._constructor_.md) |  | Constructs a new instance of the <code>BrowserFetcher</code> class |
+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"`<!-- -->.
+
+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) |  |  |
-|  [download(revision, progressCallback)](./puppeteer.browserfetcher.download.md) |  |  |
+|  [canDownload(revision)](./puppeteer.browserfetcher.candownload.md) |  | Initiates a HEAD request to check if the revision is available. |
+|  [download(revision, progressCallback)](./puppeteer.browserfetcher.download.md) |  | Initiates a GET request to download the revision from the host. |
 |  [host()](./puppeteer.browserfetcher.host.md) |  |  |
 |  [localRevisions()](./puppeteer.browserfetcher.localrevisions.md) |  |  |
 |  [platform()](./puppeteer.browserfetcher.platform.md) |  |  |
--- a/new-docs/puppeteer.browserfetcher.platform.md
+++ b/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`<!-- -->.

--- a/new-docs/puppeteer.browserfetcher.product.md
+++ b/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`<!-- -->.

--- a/new-docs/puppeteer.browserfetcher.remove.md
+++ b/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`<!-- -->.
+
--- a/new-docs/puppeteer.browserfetcher.revisioninfo.md
+++ b/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.
+
--- a/new-docs/puppeteer.md
+++ b/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. |
--- a/src/node/BrowserFetcher.ts
+++ b/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
- * @param {string} platform
- * @param {string} host
- * @param {string} revision
- * @returns {string}
+ * @internal
 */
 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
-   * @param {?function(number, number):void} progressCallback
-   * @returns {!Promise<!BrowserFetcher.RevisionInfo>}
+   * Initiates a GET request to download the revision from the host.
+   * @remarks
+   * 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
-   * @returns {string}
+   * @internal
   */
  _getFolderPath(revision: string): string {
    return path.join(this._downloadsFolder, this._platform + '-' + revision);
@ -352,10 +419,7 @@ function parseFolderPath(
 }

 /**
- * @param {string} url
- * @param {string} destinationPath
- * @param {?function(number, number):void} progressCallback
- * @returns {!Promise}
+ * @internal
 */
 function downloadFile(
  url: string,
@ -415,9 +479,7 @@ function install(archivePath: string, folderPath: string): Promise<unknown> {
 }

 /**
- * @param {string} tarPath
- * @param {string} folderPath
- * @returns {!Promise<?Error>}
+ * @internal
 */
 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
- *
- * @param {string} dmgPath
- * @param {string} folderPath
- * @returns {!Promise<?Error>}
+ * @internal
 */
 function installDMG(dmgPath: string, folderPath: string): Promise<void> {
  let mountPath;