docs: improve docs (#9988)

docs/browsers-api/browsers.computeexecutablepath.md

@@ -7,14 +7,16 @@ sidebar_label: computeExecutablePath
 #### Signature:
 
 ```typescript
-export declare function computeExecutablePath(options: Options): string;
+export declare function computeExecutablePath(
+  options: ComputeExecutablePathOptions
+): string;
 ```
 
 ## Parameters
 
 | Parameter | Type                                                  | Description |
-| --------- | -------------------------------- | ----------- |
-| options   | [Options](./browsers.options.md) |             |
+| --------- | ----------------------------------------------------- | ----------- |
+| options   | [ComputeExecutablePathOptions](./browsers.options.md) |             |
 
 **Returns:**
 

docs/browsers-api/browsers.install.md

@@ -20,4 +20,4 @@ export declare function install(
 
 **Returns:**
 
-Promise<InstalledBrowser>
+Promise<[InstalledBrowser](./browsers.installedbrowser.md)>

docs/browsers-api/browsers.installedbrowser.md

@@ -0,0 +1,18 @@
+---
+sidebar_label: InstalledBrowser
+---
+
+# InstalledBrowser type
+
+#### Signature:
+
+```typescript
+export type InstalledBrowser = {
+  path: string;
+  browser: Browser;
+  buildId: string;
+  platform: BrowserPlatform;
+};
+```
+
+**References:** [Browser](./browsers.browser.md), [BrowserPlatform](./browsers.browserplatform.md)

docs/browsers-api/browsers.launch.md

@@ -18,4 +18,4 @@ export declare function launch(opts: LaunchOptions): Process;
 
 **Returns:**
 
-Process
+[Process](./browsers.process.md)

docs/browsers-api/browsers.options.md

@@ -7,7 +7,7 @@ sidebar_label: Options
 #### Signature:
 
 ```typescript
-export interface Options
+export interface ComputeExecutablePathOptions
 ```
 
 ## Properties

docs/browsers-api/browsers.process._constructor_.md

@@ -0,0 +1,21 @@
+---
+sidebar_label: Process.(constructor)
+---
+
+# Process.(constructor)
+
+Constructs a new instance of the `Process` class
+
+#### Signature:
+
+```typescript
+class Process {
+  constructor(opts: LaunchOptions);
+}
+```
+
+## Parameters
+
+| Parameter | Type                                         | Description |
+| --------- | -------------------------------------------- | ----------- |
+| opts      | [LaunchOptions](./browsers.launchoptions.md) |             |

docs/browsers-api/browsers.process.close.md

@@ -0,0 +1,17 @@
+---
+sidebar_label: Process.close
+---
+
+# Process.close() method
+
+#### Signature:
+
+```typescript
+class Process {
+  close(): Promise<void>;
+}
+```
+
+**Returns:**
+
+Promise&lt;void&gt;

docs/browsers-api/browsers.process.hasclosed.md

@@ -0,0 +1,17 @@
+---
+sidebar_label: Process.hasClosed
+---
+
+# Process.hasClosed() method
+
+#### Signature:
+
+```typescript
+class Process {
+  hasClosed(): Promise<void>;
+}
+```
+
+**Returns:**
+
+Promise&lt;void&gt;

docs/browsers-api/browsers.process.kill.md

@@ -0,0 +1,17 @@
+---
+sidebar_label: Process.kill
+---
+
+# Process.kill() method
+
+#### Signature:
+
+```typescript
+class Process {
+  kill(): void;
+}
+```
+
+**Returns:**
+
+void

docs/browsers-api/browsers.process.md

@@ -0,0 +1,32 @@
+---
+sidebar_label: Process
+---
+
+# Process class
+
+#### Signature:
+
+```typescript
+export declare class Process
+```
+
+## Constructors
+
+| Constructor                                                | Modifiers | Description                                                 |
+| ---------------------------------------------------------- | --------- | ----------------------------------------------------------- |
+| [(constructor)(opts)](./browsers.process._constructor_.md) |           | Constructs a new instance of the <code>Process</code> class |
+
+## Properties
+
+| Property    | Modifiers             | Type                      | Description |
+| ----------- | --------------------- | ------------------------- | ----------- |
+| nodeProcess | <code>readonly</code> | childProcess.ChildProcess |             |
+
+## Methods
+
+| Method                                                                       | Modifiers | Description |
+| ---------------------------------------------------------------------------- | --------- | ----------- |
+| [close()](./browsers.process.close.md)                                       |           |             |
+| [hasClosed()](./browsers.process.hasclosed.md)                               |           |             |
+| [kill()](./browsers.process.kill.md)                                         |           |             |
+| [waitForLineOutput(regex, timeout)](./browsers.process.waitforlineoutput.md) |           |             |

docs/browsers-api/browsers.process.waitforlineoutput.md

@@ -0,0 +1,24 @@
+---
+sidebar_label: Process.waitForLineOutput
+---
+
+# Process.waitForLineOutput() method
+
+#### Signature:
+
+```typescript
+class Process {
+  waitForLineOutput(regex: RegExp, timeout?: number): Promise<string>;
+}
+```
+
+## Parameters
+
+| Parameter | Type   | Description  |
+| --------- | ------ | ------------ |
+| regex     | RegExp |              |
+| timeout   | number | _(Optional)_ |
+
+**Returns:**
+
+Promise&lt;string&gt;

docs/browsers-api/index.md

@@ -9,6 +9,7 @@ sidebar_label: API
 | Class                                      | Description |
 | ------------------------------------------ | ----------- |
 | [CLI](./browsers.cli.md)                   |             |
+| [Process](./browsers.process.md)           |             |
 | [TimeoutError](./browsers.timeouterror.md) |             |
 
 ## Enumerations
@@ -52,5 +53,6 @@ sidebar_label: API
 ## Type Aliases
 
 | Type Alias                                         | Description |
-| -------------------------------------------- | ----------- |
+| -------------------------------------------------- | ----------- |
+| [InstalledBrowser](./browsers.installedbrowser.md) |             |
 | [LaunchOptions](./browsers.launchoptions.md)       |             |

packages/browsers/src/CLI.ts

@@ -62,6 +62,9 @@ type ClearArgs = {
   path?: string;
 };
 
+/**
+ * @public
+ */
 export class CLI {
   #cachePath;
   #rl?: readline.Interface;
@@ -275,6 +278,9 @@ export class CLI {
   }
 }
 
+/**
+ * @public
+ */
 export function makeProgressCallback(
   browser: Browser,
   buildId: string

packages/browsers/src/browser-data/browser-data.ts

@@ -47,6 +47,9 @@ export const executablePathByBrowser = {
 
 export {Browser, BrowserPlatform, ChromeReleaseChannel};
 
+/**
+ * @public
+ */
 export async function resolveBuildId(
   browser: Browser,
   platform: BrowserPlatform,
@@ -74,6 +77,9 @@ export async function resolveBuildId(
   return tag;
 }
 
+/**
+ * @public
+ */
 export async function createProfile(
   browser: Browser,
   opts: ProfileOptions
@@ -87,6 +93,9 @@ export async function createProfile(
   }
 }
 
+/**
+ * @public
+ */
 export function resolveSystemExecutablePath(
   browser: Browser,
   platform: BrowserPlatform,

packages/browsers/src/browser-data/types.ts

@@ -19,6 +19,8 @@ import * as firefox from './firefox.js';
 
 /**
  * Supported browsers.
+ *
+ * @public
  */
 export enum Browser {
   CHROME = 'chrome',
@@ -29,6 +31,8 @@ export enum Browser {
 /**
  * Platform names used to identify a OS platfrom x architecture combination in the way
  * that is relevant for the browser download.
+ *
+ * @public
  */
 export enum BrowserPlatform {
   LINUX = 'linux',
@@ -44,15 +48,24 @@ export const downloadUrls = {
   [Browser.FIREFOX]: firefox.resolveDownloadUrl,
 };
 
+/**
+ * @public
+ */
 export enum BrowserTag {
   LATEST = 'latest',
 }
 
+/**
+ * @public
+ */
 export interface ProfileOptions {
   preferences: Record<string, unknown>;
   path: string;
 }
 
+/**
+ * @public
+ */
 export enum ChromeReleaseChannel {
   STABLE = 'stable',
   DEV = 'dev',

packages/browsers/src/detectPlatform.ts

@@ -18,6 +18,9 @@ import os from 'os';
 
 import {BrowserPlatform} from './browser-data/browser-data.js';
 
+/**
+ * @public
+ */
 export function detectBrowserPlatform(): BrowserPlatform | undefined {
   const platform = os.platform();
   switch (platform) {

packages/browsers/src/install.ts

@@ -97,6 +97,9 @@ export interface InstallOptions {
   unpack?: boolean;
 }
 
+/**
+ * @public
+ */
 export type InstalledBrowser = {
   path: string;
   browser: Browser;
@@ -104,6 +107,9 @@ export type InstalledBrowser = {
   platform: BrowserPlatform;
 };
 
+/**
+ * @public
+ */
 export async function install(
   options: InstallOptions
 ): Promise<InstalledBrowser> {
@@ -194,6 +200,9 @@ export async function install(
   };
 }
 
+/**
+ * @public
+ */
 export async function canDownload(options: InstallOptions): Promise<boolean> {
   options.platform ??= detectBrowserPlatform();
   if (!options.platform) {

packages/browsers/src/launch.ts

@@ -36,7 +36,7 @@ const debugLaunch = debug('puppeteer:browsers:launcher');
 /**
  * @public
  */
-export interface Options {
+export interface ComputeExecutablePathOptions {
   /**
    * Root path to the storage directory.
    */
@@ -58,7 +58,12 @@ export interface Options {
   buildId: string;
 }
 
-export function computeExecutablePath(options: Options): string {
+/**
+ * @public
+ */
+export function computeExecutablePath(
+  options: ComputeExecutablePathOptions
+): string {
   options.platform ??= detectBrowserPlatform();
   if (!options.platform) {
     throw new Error(
@@ -95,6 +100,10 @@ export interface SystemOptions {
    */
   channel: ChromeReleaseChannel;
 }
+
+/**
+ * @public
+ */
 export function computeSystemExecutablePath(options: SystemOptions): string {
   options.platform ??= detectBrowserPlatform();
   if (!options.platform) {
@@ -117,6 +126,9 @@ export function computeSystemExecutablePath(options: SystemOptions): string {
   return path;
 }
 
+/**
+ * @public
+ */
 export type LaunchOptions = {
   executablePath: string;
   pipe?: boolean;
@@ -130,16 +142,29 @@ export type LaunchOptions = {
   onExit?: () => Promise<void>;
 };
 
+/**
+ * @public
+ */
 export function launch(opts: LaunchOptions): Process {
   return new Process(opts);
 }
 
+/**
+ * @public
+ */
 export const CDP_WEBSOCKET_ENDPOINT_REGEX =
   /^DevTools listening on (ws:\/\/.*)$/;
+
+/**
+ * @public
+ */
 export const WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX =
   /^WebDriver BiDi listening on (ws:\/\/.*)$/;
 
-class Process {
+/**
+ * @public
+ */
+export class Process {
   #executablePath;
   #args: string[];
   #browserProcess: childProcess.ChildProcess;
@@ -454,6 +479,9 @@ export function isErrnoException(obj: unknown): obj is NodeJS.ErrnoException {
   );
 }
 
+/**
+ * @public
+ */
 export class TimeoutError extends Error {
   /**
    * @internal

packages/browsers/src/main.ts

@@ -20,12 +20,18 @@ export {
   computeSystemExecutablePath,
   TimeoutError,
   LaunchOptions,
-  Options,
+  ComputeExecutablePathOptions as Options,
   SystemOptions,
   CDP_WEBSOCKET_ENDPOINT_REGEX,
   WEBDRIVER_BIDI_WEBSOCKET_ENDPOINT_REGEX,
+  Process,
 } from './launch.js';
-export {install, canDownload, InstallOptions} from './install.js';
+export {
+  install,
+  canDownload,
+  InstallOptions,
+  InstalledBrowser,
+} from './install.js';
 export {detectBrowserPlatform} from './detectPlatform.js';
 export {
   resolveBuildId,