From 7d1734a5fa8f4c5e69b91e97bc44937440655441 Mon Sep 17 00:00:00 2001 From: Alex Rudenko Date: Thu, 6 Apr 2023 14:50:22 +0200 Subject: [PATCH] docs: improve docs (#9988) --- .../browsers.computeexecutablepath.md | 10 +++--- docs/browsers-api/browsers.install.md | 2 +- .../browsers-api/browsers.installedbrowser.md | 18 ++++++++++ docs/browsers-api/browsers.launch.md | 2 +- docs/browsers-api/browsers.options.md | 2 +- .../browsers.process._constructor_.md | 21 ++++++++++++ docs/browsers-api/browsers.process.close.md | 17 ++++++++++ .../browsers.process.hasclosed.md | 17 ++++++++++ docs/browsers-api/browsers.process.kill.md | 17 ++++++++++ docs/browsers-api/browsers.process.md | 32 +++++++++++++++++ .../browsers.process.waitforlineoutput.md | 24 +++++++++++++ docs/browsers-api/index.md | 8 +++-- packages/browsers/src/CLI.ts | 6 ++++ .../browsers/src/browser-data/browser-data.ts | 9 +++++ packages/browsers/src/browser-data/types.ts | 13 +++++++ packages/browsers/src/detectPlatform.ts | 3 ++ packages/browsers/src/install.ts | 9 +++++ packages/browsers/src/launch.ts | 34 +++++++++++++++++-- packages/browsers/src/main.ts | 10 ++++-- 19 files changed, 239 insertions(+), 15 deletions(-) create mode 100644 docs/browsers-api/browsers.installedbrowser.md create mode 100644 docs/browsers-api/browsers.process._constructor_.md create mode 100644 docs/browsers-api/browsers.process.close.md create mode 100644 docs/browsers-api/browsers.process.hasclosed.md create mode 100644 docs/browsers-api/browsers.process.kill.md create mode 100644 docs/browsers-api/browsers.process.md create mode 100644 docs/browsers-api/browsers.process.waitforlineoutput.md diff --git a/docs/browsers-api/browsers.computeexecutablepath.md b/docs/browsers-api/browsers.computeexecutablepath.md index 0c0e1480..993038fe 100644 --- a/docs/browsers-api/browsers.computeexecutablepath.md +++ b/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) | | +| Parameter | Type | Description | +| --------- | ----------------------------------------------------- | ----------- | +| options | [ComputeExecutablePathOptions](./browsers.options.md) | | **Returns:** diff --git a/docs/browsers-api/browsers.install.md b/docs/browsers-api/browsers.install.md index 14fa4a42..936cf5f5 100644 --- a/docs/browsers-api/browsers.install.md +++ b/docs/browsers-api/browsers.install.md @@ -20,4 +20,4 @@ export declare function install( **Returns:** -Promise<InstalledBrowser> +Promise<[InstalledBrowser](./browsers.installedbrowser.md)> diff --git a/docs/browsers-api/browsers.installedbrowser.md b/docs/browsers-api/browsers.installedbrowser.md new file mode 100644 index 00000000..150815c4 --- /dev/null +++ b/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) diff --git a/docs/browsers-api/browsers.launch.md b/docs/browsers-api/browsers.launch.md index 84d3889e..72a68040 100644 --- a/docs/browsers-api/browsers.launch.md +++ b/docs/browsers-api/browsers.launch.md @@ -18,4 +18,4 @@ export declare function launch(opts: LaunchOptions): Process; **Returns:** -Process +[Process](./browsers.process.md) diff --git a/docs/browsers-api/browsers.options.md b/docs/browsers-api/browsers.options.md index 274d4ba0..f377b358 100644 --- a/docs/browsers-api/browsers.options.md +++ b/docs/browsers-api/browsers.options.md @@ -7,7 +7,7 @@ sidebar_label: Options #### Signature: ```typescript -export interface Options +export interface ComputeExecutablePathOptions ``` ## Properties diff --git a/docs/browsers-api/browsers.process._constructor_.md b/docs/browsers-api/browsers.process._constructor_.md new file mode 100644 index 00000000..83fad908 --- /dev/null +++ b/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) | | diff --git a/docs/browsers-api/browsers.process.close.md b/docs/browsers-api/browsers.process.close.md new file mode 100644 index 00000000..34680762 --- /dev/null +++ b/docs/browsers-api/browsers.process.close.md @@ -0,0 +1,17 @@ +--- +sidebar_label: Process.close +--- + +# Process.close() method + +#### Signature: + +```typescript +class Process { + close(): Promise; +} +``` + +**Returns:** + +Promise<void> diff --git a/docs/browsers-api/browsers.process.hasclosed.md b/docs/browsers-api/browsers.process.hasclosed.md new file mode 100644 index 00000000..1ce8e81f --- /dev/null +++ b/docs/browsers-api/browsers.process.hasclosed.md @@ -0,0 +1,17 @@ +--- +sidebar_label: Process.hasClosed +--- + +# Process.hasClosed() method + +#### Signature: + +```typescript +class Process { + hasClosed(): Promise; +} +``` + +**Returns:** + +Promise<void> diff --git a/docs/browsers-api/browsers.process.kill.md b/docs/browsers-api/browsers.process.kill.md new file mode 100644 index 00000000..f25c0591 --- /dev/null +++ b/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 diff --git a/docs/browsers-api/browsers.process.md b/docs/browsers-api/browsers.process.md new file mode 100644 index 00000000..8b5d642e --- /dev/null +++ b/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 Process class | + +## Properties + +| Property | Modifiers | Type | Description | +| ----------- | --------------------- | ------------------------- | ----------- | +| nodeProcess | readonly | 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) | | | diff --git a/docs/browsers-api/browsers.process.waitforlineoutput.md b/docs/browsers-api/browsers.process.waitforlineoutput.md new file mode 100644 index 00000000..41d94f3e --- /dev/null +++ b/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; +} +``` + +## Parameters + +| Parameter | Type | Description | +| --------- | ------ | ------------ | +| regex | RegExp | | +| timeout | number | _(Optional)_ | + +**Returns:** + +Promise<string> diff --git a/docs/browsers-api/index.md b/docs/browsers-api/index.md index ae7dcaaf..aa692ab7 100644 --- a/docs/browsers-api/index.md +++ b/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 @@ -51,6 +52,7 @@ sidebar_label: API ## Type Aliases -| Type Alias | Description | -| -------------------------------------------- | ----------- | -| [LaunchOptions](./browsers.launchoptions.md) | | +| Type Alias | Description | +| -------------------------------------------------- | ----------- | +| [InstalledBrowser](./browsers.installedbrowser.md) | | +| [LaunchOptions](./browsers.launchoptions.md) | | diff --git a/packages/browsers/src/CLI.ts b/packages/browsers/src/CLI.ts index 4a7818a6..67670022 100644 --- a/packages/browsers/src/CLI.ts +++ b/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 diff --git a/packages/browsers/src/browser-data/browser-data.ts b/packages/browsers/src/browser-data/browser-data.ts index c97fa6ac..03f95f59 100644 --- a/packages/browsers/src/browser-data/browser-data.ts +++ b/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, diff --git a/packages/browsers/src/browser-data/types.ts b/packages/browsers/src/browser-data/types.ts index 78844d2c..5b2f84d8 100644 --- a/packages/browsers/src/browser-data/types.ts +++ b/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; path: string; } +/** + * @public + */ export enum ChromeReleaseChannel { STABLE = 'stable', DEV = 'dev', diff --git a/packages/browsers/src/detectPlatform.ts b/packages/browsers/src/detectPlatform.ts index 8ecee194..fed8c2e2 100644 --- a/packages/browsers/src/detectPlatform.ts +++ b/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) { diff --git a/packages/browsers/src/install.ts b/packages/browsers/src/install.ts index fad4d128..48f25d7c 100644 --- a/packages/browsers/src/install.ts +++ b/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 { @@ -194,6 +200,9 @@ export async function install( }; } +/** + * @public + */ export async function canDownload(options: InstallOptions): Promise { options.platform ??= detectBrowserPlatform(); if (!options.platform) { diff --git a/packages/browsers/src/launch.ts b/packages/browsers/src/launch.ts index 5e61ebdd..c73f999e 100644 --- a/packages/browsers/src/launch.ts +++ b/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; }; +/** + * @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 diff --git a/packages/browsers/src/main.ts b/packages/browsers/src/main.ts index 42dd875f..2a16e8db 100644 --- a/packages/browsers/src/main.ts +++ b/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,