From 2e220df7acdafa7b7a009d747bde413a48944123 Mon Sep 17 00:00:00 2001 From: Pavel Feldman Date: Fri, 18 Dec 2020 15:31:34 -0800 Subject: [PATCH] docs: explicitly annotate methods and parameters (#4771) --- docs-src/api-body.md | 976 ++++++++++++------------ docs-src/api-header.md | 4 +- docs-src/api-params.md | 30 +- docs/api.md | 1071 ++++++++++----------------- utils/doclint/cli.js | 2 +- utils/doclint/preprocessor/index.js | 28 +- utils/parse_md.js | 20 +- 7 files changed, 932 insertions(+), 1199 deletions(-) diff --git a/docs-src/api-body.md b/docs-src/api-body.md index 435d243983..2e08da12e9 100644 --- a/docs-src/api-body.md +++ b/docs-src/api-body.md @@ -1,8 +1,8 @@ # class: Browser * extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) -A Browser is created when Playwright connects to a browser instance, either through [browserType.launch()]() or -[browserType.connect()](). +A Browser is created when Playwright connects to a browser instance, either through [`method: BrowserType.launch`]() or +[`method: BrowserType.connect`](). An example of using a [Browser] to create a [Page]: @@ -17,9 +17,9 @@ const { firefox } = require('playwright'); // Or 'chromium' or 'webkit'. })(); ``` -See [ChromiumBrowser], [FirefoxBrowser] and [WebKitBrowser] for browser-specific features. Note that -[browserType.connect()]() and [browserType.launch()]() always return a specific browser instance, based on the browser -being connected to or launched. +See [ChromiumBrowser], [FirefoxBrowser] and [WebKitBrowser] for browser-specific features. Note that [`method: +BrowserType.connect`]() and [`method: BrowserType.launch`]() always return a specific browser instance, based on the +browser being connected to or launched. @@ -28,15 +28,15 @@ being connected to or launched. Emitted when Browser gets disconnected from the browser application. This might happen because of one of the following: * Browser application is closed or crashed. -* The [browser.close()]() method was called. +* The [`method: Browser.close`]() method was called. ## async method: Browser.close -In case this browser is obtained using [browserType.launch()](), closes the browser and all of its pages (if any were -opened). +In case this browser is obtained using [`method: BrowserType.launch`](), closes the browser and all of its pages (if any +were opened). -In case this browser is obtained using [browserType.connect()](), clears all created contexts belonging to this browser -and disconnects from the browser server. +In case this browser is obtained using [`method: BrowserType.connect`](), clears all created contexts belonging to this +browser and disconnects from the browser server. The [Browser] object itself is considered to be disposed and cannot be used anymore. @@ -86,8 +86,8 @@ Creates a new browser context. It won't share cookies/cache with other browser c Creates a new page in a new browser context. Closing this page will close the context as well. This is a convenience API that should only be used for the single-page scenarios and short snippets. Production code and -testing frameworks should explicitly create [browser.newContext()]() followed by the [browserContext.newPage()]() to -control their exact life times. +testing frameworks should explicitly create [`method: Browser.newContext`]() followed by the [`method: +BrowserContext.newPage`]() to control their exact life times. ### option: Browser.newPage.-inline- = %%-shared-context-params-list-%% @@ -129,13 +129,13 @@ await context.close(); Emitted when Browser context gets closed. This might happen because of one of the following: * Browser context is closed. * Browser application is closed or crashed. -* The [browser.close()]() method was called. +* The [`method: Browser.close`]() method was called. ## event: BrowserContext.page - <[Page]> The event is emitted when a new Page is created in the BrowserContext. The page may still be loading. The event will -also fire for popup pages. See also [page.on('popup')]() to receive events about popups relevant to a specific page. +also fire for popup pages. See also [`event: Page.popup`]() to receive events about popups relevant to a specific page. The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a popup with `window.open('http://example.com')`, this event will fire when the network request to "http://example.com" is @@ -149,13 +149,13 @@ const [page] = await Promise.all([ console.log(await page.evaluate('location.href')); ``` -> **NOTE** Use [page.waitForLoadState()]() to wait until the page gets to a particular state (you should not need it in -most cases). +> **NOTE** Use [`method: Page.waitForLoadState`]() to wait until the page gets to a particular state (you should not +need it in most cases). ## async method: BrowserContext.addCookies Adds cookies into this browser context. All pages within this context will have these cookies installed. Cookies can be -obtained via [browserContext.cookies()](). +obtained via [`method: BrowserContext.cookies`](). ```js await browserContext.addCookies([cookieObject1, cookieObject2]); @@ -196,8 +196,8 @@ await browserContext.addInitScript({ }); ``` -> **NOTE** The order of evaluation of multiple scripts installed via [browserContext.addInitScript()]() and -[page.addInitScript()]() is not defined. +> **NOTE** The order of evaluation of multiple scripts installed via [`method: BrowserContext.addInitScript`]() and +[`method: Page.addInitScript`]() is not defined. ### param: BrowserContext.addInitScript.script - `script` <[function]|[string]|[Object]> @@ -209,7 +209,7 @@ Script to be evaluated in all pages in the browser context. ### param: BrowserContext.addInitScript.arg - `arg` <[Serializable]> -Optional argument to pass to `script` (only supported when passing a function). +Optional argument to pass to [`param: script`]() (only supported when passing a function). ## method: BrowserContext.browser - returns: <[null]|[Browser]> @@ -258,14 +258,14 @@ Optional list of URLs. ## async method: BrowserContext.exposeBinding -The method adds a function called `name` on the `window` object of every frame in every page in the context. When -called, the function executes `playwrightBinding` and returns a [Promise] which resolves to the return value -of `playwrightBinding`. If the `playwrightBinding` returns a [Promise], it will be awaited. +The method adds a function called [`param: name`]() on the `window` object of every frame in every page in the context. +When called, the function executes [`param: playwrightBinding`]() and returns a [Promise] which resolves to the return +value of [`param: playwrightBinding`](). If the [`param: playwrightBinding`]() returns a [Promise], it will be awaited. -The first argument of the `playwrightBinding` function contains information about the caller: `{ browserContext: -BrowserContext, page: Page, frame: Frame }`. +The first argument of the [`param: playwrightBinding`]() function contains information about the caller: `{ +browserContext: BrowserContext, page: Page, frame: Frame }`. -See [page.exposeBinding()]() for page-only version. +See [`method: Page.exposeBinding`]() for page-only version. An example of exposing page URL to all frames in all pages in the context: @@ -323,13 +323,13 @@ supported. When passing by value, multiple arguments are supported. ## async method: BrowserContext.exposeFunction -The method adds a function called `name` on the `window` object of every frame in every page in the context. When -called, the function executes `playwrightFunction` and returns a [Promise] which resolves to the return value -of `playwrightFunction`. +The method adds a function called [`param: name`]() on the `window` object of every frame in every page in the context. +When called, the function executes [`param: playwrightFunction`]() and returns a [Promise] which resolves to the return +value of [`param: playwrightFunction`](). -If the `playwrightFunction` returns a [Promise], it will be awaited. +If the [`param: playwrightFunction`]() returns a [Promise], it will be awaited. -See [page.exposeFunction()]() for page-only version. +See [`method: Page.exposeFunction`]() for page-only version. An example of adding an `md5` function to all pages in the context: @@ -404,7 +404,8 @@ Creates a new page in the browser context. ## method: BrowserContext.pages - returns: <[Array]<[Page]>> -Returns all open pages in the context. Non visible pages, such as `"background_page"`, will not be listed here. You can find them using [chromiumBrowserContext.backgroundPages()](). +Returns all open pages in the context. Non visible pages, such as `"background_page"`, will not be listed here. You can +find them using [`method: ChromiumBrowserContext.backgroundPages`](). ## async method: BrowserContext.route @@ -431,7 +432,7 @@ await page.goto('https://example.com'); await browser.close(); ``` -Page routes (set up with [page.route()]()) take precedence over browser context routes when request matches both +Page routes (set up with [`method: Page.route`]()) take precedence over browser context routes when request matches both handlers. > **NOTE** Enabling routing disables http cache. @@ -449,15 +450,15 @@ handler function to route the request. ## method: BrowserContext.setDefaultNavigationTimeout This setting will change the default maximum navigation time for the following methods and related shortcuts: -* [page.goBack()]() -* [page.goForward()]() -* [page.goto()]() -* [page.reload()]() -* [page.setContent()]() -* [page.waitForNavigation()]() +* [`method: Page.goBack`]() +* [`method: Page.goForward`]() +* [`method: Page.goto`]() +* [`method: Page.reload`]() +* [`method: Page.setContent`]() +* [`method: Page.waitForNavigation`]() -> **NOTE** [page.setDefaultNavigationTimeout()]() and [page.setDefaultTimeout()]() take priority over -[browserContext.setDefaultNavigationTimeout()](). +> **NOTE** [`method: Page.setDefaultNavigationTimeout`]() and [`method: Page.setDefaultTimeout`]() take priority over +[`method: BrowserContext.setDefaultNavigationTimeout`](). ### param: BrowserContext.setDefaultNavigationTimeout.timeout - `timeout` <[number]> @@ -466,10 +467,10 @@ Maximum navigation time in milliseconds ## method: BrowserContext.setDefaultTimeout -This setting will change the default maximum time for all the methods accepting `timeout` option. +This setting will change the default maximum time for all the methods accepting [`param: timeout`]() option. -> **NOTE** [page.setDefaultNavigationTimeout()](), [page.setDefaultTimeout()]() and -[browserContext.setDefaultNavigationTimeout()]() take priority over [browserContext.setDefaultTimeout()](). +> **NOTE** [`method: Page.setDefaultNavigationTimeout`](), [`method: Page.setDefaultTimeout`]() and [`method: +BrowserContext.setDefaultNavigationTimeout`]() take priority over [`method: BrowserContext.setDefaultTimeout`](). ### param: BrowserContext.setDefaultTimeout.timeout - `timeout` <[number]> @@ -479,8 +480,8 @@ Maximum time in milliseconds ## async method: BrowserContext.setExtraHTTPHeaders The extra HTTP headers will be sent with every request initiated by any page in the context. These headers are merged -with page-specific extra HTTP headers set with [page.setExtraHTTPHeaders()](). If page overrides a particular header, -page-specific header value will be used instead of the browser context header value. +with page-specific extra HTTP headers set with [`method: Page.setExtraHTTPHeaders`](). If page overrides a particular +header, page-specific header value will be used instead of the browser context header value. > **NOTE** `browserContext.setExtraHTTPHeaders` does not guarantee the order of headers in the outgoing requests. @@ -497,8 +498,8 @@ Sets the context's geolocation. Passing `null` or `undefined` emulates position await browserContext.setGeolocation({latitude: 59.95, longitude: 30.31667}); ``` -> **NOTE** Consider using [browserContext.grantPermissions()]() to grant permissions for the browser context pages to -read its geolocation. +> **NOTE** Consider using [`method: BrowserContext.grantPermissions`]() to grant permissions for the browser context +pages to read its geolocation. ### param: BrowserContext.setGeolocation.geolocation - `geolocation` <[null]|[Object]> @@ -548,22 +549,25 @@ Returns storage state for this browser context, contains current cookies and loc ### option: BrowserContext.storageState.path - `path` <[string]> -The file path to save the storage state to. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). If no path is provided, storage state is still returned, but won't be saved to the disk. +The file path to save the storage state to. If [`option: path`]() is a relative path, then it is resolved relative to +[current working directory](https://nodejs.org/api/process.html#process_process_cwd). If no path is provided, storage +state is still returned, but won't be saved to the disk. ## async method: BrowserContext.unroute -Removes a route created with [browserContext.route()](). When `handler` is not specified, removes all routes for the -`url`. +Removes a route created with [`method: BrowserContext.route`](). When [`param: handler`]() is not specified, removes all +routes for the [`param: url`](). ### param: BrowserContext.unroute.url - `url` <[string]|[RegExp]|[function]\([URL]\):[boolean]> -A glob pattern, regex pattern or predicate receiving [URL] used to register a routing with [browserContext.route()](). +A glob pattern, regex pattern or predicate receiving [URL] used to register a routing with [`method: +BrowserContext.route`](). ### param: BrowserContext.unroute.handler - `handler` <[function]\([Route], [Request]\)> -Optional handler function used to register a routing with [browserContext.route()](). +Optional handler function used to register a routing with [`method: BrowserContext.route`](). ## async method: BrowserContext.waitForEvent - returns: <[Object]> @@ -691,7 +695,7 @@ await new Promise((resolve, reject) => { - <[Dialog]> Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Playwright can respond -to the dialog via [dialog.accept()]() or [dialog.dismiss()]() methods. +to the dialog via [`method: Dialog.accept`]() or [`method: Dialog.dismiss`]() methods. ## event: Page.domcontentloaded @@ -712,7 +716,7 @@ download is not performed and user has no access to the downloaded files. - <[FileChooser]> Emitted when a file chooser is supposed to appear, such as after clicking the ``. Playwright can -respond to it via setting the input files using [fileChooser.setFiles()]() that can be uploaded after that. +respond to it via setting the input files using [`method: FileChooser.setFiles`]() that can be uploaded after that. ```js page.on('filechooser', async (fileChooser) => { @@ -747,8 +751,8 @@ Emitted when an uncaught exception happens within the page. ## event: Page.popup - <[Page]> Page corresponding to "popup" window -Emitted when the page opens a new tab or window. This event is emitted in addition to the [browserContext.on('page')](), -but only for popups relevant to this page. +Emitted when the page opens a new tab or window. This event is emitted in addition to the [`event: +BrowserContext.page`](), but only for popups relevant to this page. The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a popup with `window.open('http://example.com')`, this event will fire when the network request to "http://example.com" is @@ -762,14 +766,14 @@ const [popup] = await Promise.all([ console.log(await popup.evaluate('location.href')); ``` -> **NOTE** Use [page.waitForLoadState()]() to wait until the page gets to a particular state (you should not need it in -most cases). +> **NOTE** Use [`method: Page.waitForLoadState`]() to wait until the page gets to a particular state (you should not +need it in most cases). ## event: Page.request - <[Request]> Emitted when a page issues a request. The [request] object is read-only. In order to intercept and mutate requests, see -[page.route()]() or [browserContext.route()](). +[`method: Page.route`]() or [`method: BrowserContext.route`](). ## event: Page.requestfailed - <[Request]> @@ -777,7 +781,7 @@ Emitted when a page issues a request. The [request] object is read-only. In orde Emitted when a request fails, for example by timing out. > **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request -will complete with [page.on('requestfinished')]() event and not with [page.on('requestfailed')](). +will complete with [`event: Page.requestfinished`]() event and not with [`event: Page.requestfailed`](). ## event: Page.requestfinished - <[Request]> @@ -808,7 +812,7 @@ page. The method finds an element matching the specified selector within the page. If no elements match the selector, the return value resolves to `null`. -Shortcut for main frame's [frame.$()](). +Shortcut for main frame's [`method: Frame.$`](). ### param: Page.$.selector = %%-query-selector-%% @@ -818,7 +822,7 @@ Shortcut for main frame's [frame.$()](). The method finds all elements matching the specified selector within the page. If no elements match the selector, the return value resolves to `[]`. -Shortcut for main frame's [frame.$$()](). +Shortcut for main frame's [`method: Frame.$$`](). ### param: Page.$$.selector = %%-query-selector-%% @@ -826,9 +830,11 @@ Shortcut for main frame's [frame.$$()](). - returns: <[Serializable]> The method finds an element matching the specified selector within the page and passes it as a first argument to -`pageFunction`. If no elements match the selector, the method throws an error. Returns the value of `pageFunction`. +[`param: pageFunction`](). If no elements match the selector, the method throws an error. Returns the value of [`param: +pageFunction`](). -If `pageFunction` returns a [Promise], then `page.$eval` would wait for the promise to resolve and return its value. +If [`param: pageFunction`]() returns a [Promise], then [`method: Page.$eval`]() would wait for the promise to resolve and return its +value. Examples: @@ -838,7 +844,7 @@ const preloadHref = await page.$eval('link[rel=preload]', el => el.href); const html = await page.$eval('.main-container', (e, suffix) => e.outerHTML + suffix, 'hello'); ``` -Shortcut for main frame's [frame.$eval()](). +Shortcut for main frame's [`method: Frame.$eval`](). ### param: Page.$eval.selector = %%-query-selector-%% @@ -850,15 +856,16 @@ Function to be evaluated in browser context ### param: Page.$eval.arg - `arg` <[EvaluationArgument]> -Optional argument to pass to `pageFunction` +Optional argument to pass to [`param: pageFunction`]() ## async method: Page.$$eval - returns: <[Serializable]> The method finds all elements matching the specified selector within the page and passes an array of matched elements as -a first argument to `pageFunction`. Returns the result of `pageFunction` invocation. +a first argument to [`param: pageFunction`](). Returns the result of [`param: pageFunction`]() invocation. -If `pageFunction` returns a [Promise], then `page.$$eval` would wait for the promise to resolve and return its value. +If [`param: pageFunction`]() returns a [Promise], then [`method: Page.$$eval`]() would wait for the promise to resolve and return +its value. Examples: @@ -876,7 +883,7 @@ Function to be evaluated in browser context ### param: Page.$$eval.arg - `arg` <[EvaluationArgument]> -Optional argument to pass to `pageFunction` +Optional argument to pass to [`param: pageFunction`]() ## namespace: Page.accessibility - returns: <[Accessibility]> @@ -901,8 +908,8 @@ const preloadFile = fs.readFileSync('./preload.js', 'utf8'); await page.addInitScript(preloadFile); ``` -> **NOTE** The order of evaluation of multiple scripts installed via [browserContext.addInitScript()]() and -[page.addInitScript()]() is not defined. +> **NOTE** The order of evaluation of multiple scripts installed via [`method: BrowserContext.addInitScript`]() and +[`method: Page.addInitScript`]() is not defined. ### param: Page.addInitScript.script - `script` <[function]|[string]|[Object]> @@ -914,7 +921,7 @@ Script to be evaluated in the page. ### param: Page.addInitScript.arg - `arg` <[Serializable]> -Optional argument to pass to `script` (only supported when passing a function). +Optional argument to pass to [`param: script`]() (only supported when passing a function). ## async method: Page.addScriptTag - returns: <[ElementHandle]> @@ -922,7 +929,7 @@ Optional argument to pass to `script` (only supported when passing a function). Adds a `