docs: document launch in browsers better (#13002)

docs/browsers-api/browsers.launch.md

@@ -4,6 +4,8 @@ sidebar_label: launch
 
 # launch() function
 
+Launches a browser process according to [LaunchOptions](./browsers.launchoptions.md).
+
 ### Signature
 
 ```typescript

docs/browsers-api/browsers.launchoptions.md

@@ -47,6 +47,8 @@ string\[\]
 
 </td><td>
 
+Additional arguments to pass to the executable when launching.
+
 </td><td>
 
 </td></tr>
@@ -64,8 +66,12 @@ boolean
 
 </td><td>
 
+Whether to spawn process in the [detached](https://nodejs.org/api/child_process.html#optionsdetached) mode.
+
 </td><td>
 
+`true` except on Windows.
+
 </td></tr>
 <tr><td>
 
@@ -81,8 +87,12 @@ boolean
 
 </td><td>
 
+If true, forwards the browser's process stdout and stderr to the Node's process stdout and stderr.
+
 </td><td>
 
+`false`.
+
 </td></tr>
 <tr><td>
 
@@ -98,6 +108,8 @@ Record&lt;string, string \| undefined&gt;
 
 </td><td>
 
+Environment variables to set for the browser process.
+
 </td><td>
 
 </td></tr>
@@ -113,6 +125,8 @@ string
 
 </td><td>
 
+Absolute path to the browser's executable.
+
 </td><td>
 
 </td></tr>
@@ -130,8 +144,12 @@ boolean
 
 </td><td>
 
+Handles SIGHUP in the Node process and tries to gracefully close the browser process.
+
 </td><td>
 
+`true`.
+
 </td></tr>
 <tr><td>
 
@@ -147,8 +165,12 @@ boolean
 
 </td><td>
 
+Handles SIGINT in the Node process and tries to kill the browser process.
+
 </td><td>
 
+`true`.
+
 </td></tr>
 <tr><td>
 
@@ -164,8 +186,12 @@ boolean
 
 </td><td>
 
+Handles SIGTERM in the Node process and tries to gracefully close the browser process.
+
 </td><td>
 
+`true`.
+
 </td></tr>
 <tr><td>
 
@@ -181,6 +207,8 @@ boolean
 
 </td><td>
 
+A callback to run after the browser process exits or before the process will be closed via the [Process.close()](./browsers.process.close.md) call (including when handling signals). The callback is only run once.
+
 </td><td>
 
 </td></tr>
@@ -198,7 +226,11 @@ boolean
 
 </td><td>
 
+Configures stdio streams to open two additional streams for automation over those streams instead of WebSocket.
+
 </td><td>
 
+`false`.
+
 </td></tr>
 </tbody></table>

docs/browsers-api/index.md

@@ -220,6 +220,8 @@ Returns a version comparator for the given browser that can be used to sort brow
 
 </td><td>
 
+Launches a browser process according to [LaunchOptions](./browsers.launchoptions.md).
+
 </td></tr>
 <tr><td>
 

packages/browsers/src/launch.ts

@@ -104,19 +104,69 @@ export function computeSystemExecutablePath(options: SystemOptions): string {
  * @public
  */
 export interface LaunchOptions {
+  /**
+   * Absolute path to the browser's executable.
+   */
   executablePath: string;
+  /**
+   * Configures stdio streams to open two additional streams for automation over
+   * those streams instead of WebSocket.
+   *
+   * @defaultValue `false`.
+   */
   pipe?: boolean;
+  /**
+   * If true, forwards the browser's process stdout and stderr to the Node's
+   * process stdout and stderr.
+   *
+   * @defaultValue `false`.
+   */
   dumpio?: boolean;
+  /**
+   * Additional arguments to pass to the executable when launching.
+   */
   args?: string[];
+  /**
+   * Environment variables to set for the browser process.
+   */
   env?: Record<string, string | undefined>;
+  /**
+   * Handles SIGINT in the Node process and tries to kill the browser process.
+   *
+   * @defaultValue `true`.
+   */
   handleSIGINT?: boolean;
+  /**
+   * Handles SIGTERM in the Node process and tries to gracefully close the browser
+   * process.
+   *
+   * @defaultValue `true`.
+   */
   handleSIGTERM?: boolean;
+  /**
+   * Handles SIGHUP in the Node process and tries to gracefully close the browser process.
+   *
+   * @defaultValue `true`.
+   */
   handleSIGHUP?: boolean;
+  /**
+   * Whether to spawn process in the {@link https://nodejs.org/api/child_process.html#optionsdetached | detached}
+   * mode.
+   *
+   * @defaultValue `true` except on Windows.
+   */
   detached?: boolean;
+  /**
+   * A callback to run after the browser process exits or before the process
+   * will be closed via the {@link Process.close} call (including when handling
+   * signals). The callback is only run once.
+   */
   onExit?: () => Promise<void>;
 }
 
 /**
+ * Launches a browser process according to {@link LaunchOptions}.
+ *
  * @public
  */
 export function launch(opts: LaunchOptions): Process {