From c68f57d2d0cb09f3c5e11f52b13635d81af9f3e0 Mon Sep 17 00:00:00 2001 From: Dmitry Gozman Date: Wed, 6 Apr 2022 19:02:10 -0700 Subject: [PATCH] docs: mark optional properties/arguments explicitly with "?" (#13369) Previously, we were guessing whether something is optional from the comment (looking for stuff like "defaults to" or "optional"). To remove this error-prone technique, every optional property or argument (but not option) is explicitly marked with "?". --- docs/src/api/class-androiddevice.md | 4 +- docs/src/api/class-browser.md | 2 +- docs/src/api/class-browsercontext.md | 32 +++++------ docs/src/api/class-cdpsession.md | 6 +- docs/src/api/class-coverage.md | 4 +- docs/src/api/class-dialog.md | 2 +- docs/src/api/class-electronapplication.md | 10 ++-- docs/src/api/class-elementhandle.md | 6 +- docs/src/api/class-error.md | 4 +- docs/src/api/class-frame.md | 12 ++-- docs/src/api/class-jshandle.md | 4 +- docs/src/api/class-locator.md | 8 +-- docs/src/api/class-logger.md | 2 +- docs/src/api/class-mouse.md | 2 +- docs/src/api/class-page.md | 46 +++++++-------- docs/src/api/class-response.md | 10 ++-- docs/src/api/class-route.md | 4 +- docs/src/api/class-selectors.md | 4 +- docs/src/api/class-websocket.md | 4 +- docs/src/api/class-worker.md | 4 +- docs/src/api/params.md | 34 +++++------ docs/src/api/python.md | 12 ++-- docs/src/test-api/class-test.md | 16 +++--- docs/src/test-api/class-testconfig.md | 6 +- docs/src/test-api/class-testerror.md | 12 ++-- docs/src/test-api/class-testinfo.md | 20 +++---- docs/src/test-api/class-testoptions.md | 12 ++-- docs/src/test-reporter-api/class-suite.md | 10 ++-- docs/src/test-reporter-api/class-testcase.md | 2 +- .../src/test-reporter-api/class-testresult.md | 8 +-- docs/src/test-reporter-api/class-teststep.md | 10 ++-- packages/playwright-core/types/types.d.ts | 50 ++++++++-------- packages/playwright-test/types/test.d.ts | 10 ++-- .../playwright-test/types/testReporter.d.ts | 10 ++-- utils/doclint/api_parser.js | 57 +++++++++---------- utils/generate_types/overrides.d.ts | 12 +--- 36 files changed, 220 insertions(+), 231 deletions(-) diff --git a/docs/src/api/class-androiddevice.md b/docs/src/api/class-androiddevice.md index 560e225c06..bd7e607784 100644 --- a/docs/src/api/class-androiddevice.md +++ b/docs/src/api/class-androiddevice.md @@ -344,9 +344,9 @@ Waits for event to fire and passes its value into the predicate function. Return ### param: AndroidDevice.waitForEvent.event = %%-wait-for-event-event-%% ### param: AndroidDevice.waitForEvent.optionsOrPredicate -- `optionsOrPredicate` <[function]|[Object]> +- `optionsOrPredicate` ?<[function]|[Object]> - `predicate` <[function]> receives the event data and resolves to truthy value when the waiting should resolve. - - `timeout` <[float]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to + - `timeout` ?<[float]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [`method: AndroidDevice.setDefaultTimeout`]. Either a predicate that receives an event or an options object. Optional. diff --git a/docs/src/api/class-browser.md b/docs/src/api/class-browser.md index 5912889296..4b7d3141e8 100644 --- a/docs/src/api/class-browser.md +++ b/docs/src/api/class-browser.md @@ -271,7 +271,7 @@ browser.stop_tracing() ``` ### param: Browser.startTracing.page -- `page` <[Page]> +- `page` ?<[Page]> Optional, if specified, tracing includes screenshots of the given page. diff --git a/docs/src/api/class-browsercontext.md b/docs/src/api/class-browsercontext.md index 660de17f9e..2d770f86d2 100644 --- a/docs/src/api/class-browsercontext.md +++ b/docs/src/api/class-browsercontext.md @@ -218,13 +218,13 @@ await context.AddCookiesAsync(new[] { cookie1, cookie2 }); - `cookies` <[Array]<[Object]>> - `name` <[string]> - `value` <[string]> - - `url` <[string]> either url or domain / path are required. Optional. - - `domain` <[string]> either url or domain / path are required Optional. - - `path` <[string]> either url or domain / path are required Optional. - - `expires` <[float]> Unix time in seconds. Optional. - - `httpOnly` <[boolean]> Optional. - - `secure` <[boolean]> Optional. - - `sameSite` <[SameSiteAttribute]<"Strict"|"Lax"|"None">> Optional. + - `url` ?<[string]> either url or domain / path are required. Optional. + - `domain` ?<[string]> either url or domain / path are required Optional. + - `path` ?<[string]> either url or domain / path are required Optional. + - `expires` ?<[float]> Unix time in seconds. Optional. + - `httpOnly` ?<[boolean]> Optional. + - `secure` ?<[boolean]> Optional. + - `sameSite` ?<[SameSiteAttribute]<"Strict"|"Lax"|"None">> Optional. ## async method: BrowserContext.addInitScript @@ -277,9 +277,9 @@ The order of evaluation of multiple scripts installed via [`method: BrowserConte ### param: BrowserContext.addInitScript.script * langs: js - `script` <[function]|[string]|[Object]> - - `path` <[path]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the + - `path` ?<[path]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. Optional. - - `content` <[string]> Raw script content. Optional. + - `content` ?<[string]> Raw script content. Optional. Script to be evaluated in all pages in the browser context. @@ -291,7 +291,7 @@ Script to be evaluated in all pages in the browser context. ### param: BrowserContext.addInitScript.arg * langs: js -- `arg` <[Serializable]> +- `arg` ?<[Serializable]> Optional argument to pass to [`param: script`] (only supported when passing a function). @@ -378,7 +378,7 @@ If no URLs are specified, this method returns all cookies. If URLs are specified are returned. ### param: BrowserContext.cookies.urls -- `urls` <[string]|[Array]<[string]>> +- `urls` ?<[string]|[Array]<[string]>> Optional list of URLs. @@ -1127,7 +1127,7 @@ its geolocation. - `geolocation` <[null]|[Object]> - `latitude` <[float]> Latitude between -90 and 90. - `longitude` <[float]> Longitude between -180 and 180. - - `accuracy` <[float]> Non-negative accuracy value. Defaults to `0`. + - `accuracy` ?<[float]> Non-negative accuracy value. Defaults to `0`. ## async method: BrowserContext.setHTTPCredentials * langs: js @@ -1187,13 +1187,13 @@ A glob pattern, regex pattern or predicate receiving [URL] used to register a ro ### param: BrowserContext.unroute.handler * langs: js, python -- `handler` <[function]\([Route], [Request]\)> +- `handler` ?<[function]\([Route], [Request]\)> Optional handler function used to register a routing with [`method: BrowserContext.route`]. ### param: BrowserContext.unroute.handler * langs: csharp, java -- `handler` <[function]\([Route]\)> +- `handler` ?<[function]\([Route]\)> Optional handler function used to register a routing with [`method: BrowserContext.route`]. @@ -1242,9 +1242,9 @@ Event name, same one would pass into `browserContext.on(event)`. ### param: BrowserContext.waitForEvent.optionsOrPredicate * langs: js -- `optionsOrPredicate` <[function]|[Object]> +- `optionsOrPredicate` ?<[function]|[Object]> - `predicate` <[function]> receives the event data and resolves to truthy value when the waiting should resolve. - - `timeout` <[float]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to + - `timeout` ?<[float]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [`method: BrowserContext.setDefaultTimeout`]. Either a predicate that receives an event or an options object. Optional. diff --git a/docs/src/api/class-cdpsession.md b/docs/src/api/class-cdpsession.md index 8f9943cd79..b690b7b4f0 100644 --- a/docs/src/api/class-cdpsession.md +++ b/docs/src/api/class-cdpsession.md @@ -56,9 +56,9 @@ send messages. ### param: CDPSession.send.method - `method` <[string]> -protocol method name +Protocol method name. ### param: CDPSession.send.params -- `params` <[Object]> +- `params` ?<[Object]> -Optional method parameters +Optional method parameters. diff --git a/docs/src/api/class-coverage.md b/docs/src/api/class-coverage.md index 4aeaf2ec6a..679c7dae30 100644 --- a/docs/src/api/class-coverage.md +++ b/docs/src/api/class-coverage.md @@ -61,7 +61,7 @@ Whether anonymous scripts generated by the page should be reported. Defaults to ## async method: Coverage.stopCSSCoverage - returns: <[Array]<[Object]>> - `url` <[string]> StyleSheet URL - - `text` <[string]> StyleSheet content, if available. + - `text` ?<[string]> StyleSheet content, if available. - `ranges` <[Array]<[Object]>> StyleSheet ranges that were used. Ranges are sorted and non-overlapping. - `start` <[int]> A start offset in text, inclusive - `end` <[int]> An end offset in text, exclusive @@ -76,7 +76,7 @@ CSS Coverage doesn't include dynamically injected style tags without sourceURLs. - returns: <[Array]<[Object]>> - `url` <[string]> Script URL - `scriptId` <[string]> Script ID - - `source` <[string]> Script content, if applicable. + - `source` ?<[string]> Script content, if applicable. - `functions` <[Array]<[Object]>> V8-specific coverage format. - `functionName` <[string]> - `isBlockCoverage` <[boolean]> diff --git a/docs/src/api/class-dialog.md b/docs/src/api/class-dialog.md index 2915851d15..55bb757611 100644 --- a/docs/src/api/class-dialog.md +++ b/docs/src/api/class-dialog.md @@ -113,7 +113,7 @@ When listener is present, it **must** either [`method: Dialog.accept`] or [`meth Returns when the dialog has been accepted. ### param: Dialog.accept.promptText -- `promptText` <[string]> +- `promptText` ?<[string]> A text to enter in prompt. Does not cause any effects if the dialog's `type` is not prompt. Optional. diff --git a/docs/src/api/class-electronapplication.md b/docs/src/api/class-electronapplication.md index c3df783c9a..80f25302fa 100644 --- a/docs/src/api/class-electronapplication.md +++ b/docs/src/api/class-electronapplication.md @@ -79,7 +79,7 @@ some additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infini ### param: ElectronApplication.evaluate.expression = %%-evaluate-expression-%% ### param: ElectronApplication.evaluate.arg -- `arg` <[EvaluationArgument]> +- `arg` ?<[EvaluationArgument]> Optional argument to pass to [`param: expression`]. @@ -96,7 +96,9 @@ If the function passed to the [`method: ElectronApplication.evaluateHandle`] ret ### param: ElectronApplication.evaluateHandle.expression = %%-evaluate-expression-%% ### param: ElectronApplication.evaluateHandle.arg -- `arg` <[EvaluationArgument]> +- `arg` ?<[EvaluationArgument]> + +Optional argument to pass to [`param: expression`]. ## async method: ElectronApplication.firstWindow - returns: <[Page]> @@ -133,9 +135,9 @@ const [window] = await Promise.all([ ### param: ElectronApplication.waitForEvent.optionsOrPredicate * langs: js -- `optionsOrPredicate` <[function]|[Object]> +- `optionsOrPredicate` ?<[function]|[Object]> - `predicate` <[function]> receives the event data and resolves to truthy value when the waiting should resolve. - - `timeout` <[float]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to + - `timeout` ?<[float]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [`method: BrowserContext.setDefaultTimeout`]. Either a predicate that receives an event or an options object. Optional. diff --git a/docs/src/api/class-elementhandle.md b/docs/src/api/class-elementhandle.md index 25805e742c..b40d48bd2f 100644 --- a/docs/src/api/class-elementhandle.md +++ b/docs/src/api/class-elementhandle.md @@ -330,7 +330,7 @@ await elementHandle.DispatchEventAsync("dragstart", new Dictionary +- `eventInit` ?<[EvaluationArgument]> Optional event-specific initialization properties. @@ -386,7 +386,7 @@ Assert.AreEqual("10", await tweetHandle.EvalOnSelectorAsync(".retweets", "node = ### param: ElementHandle.evalOnSelector.expression = %%-evaluate-expression-%% ### param: ElementHandle.evalOnSelector.arg -- `arg` <[EvaluationArgument]> +- `arg` ?<[EvaluationArgument]> Optional argument to pass to [`param: expression`]. @@ -444,7 +444,7 @@ Assert.AreEqual(new [] { "Hello!", "Hi!" }, await feedHandle.EvalOnSelectorAllAs ### param: ElementHandle.evalOnSelectorAll.expression = %%-evaluate-expression-%% ### param: ElementHandle.evalOnSelectorAll.arg -- `arg` <[EvaluationArgument]> +- `arg` ?<[EvaluationArgument]> Optional argument to pass to [`param: expression`]. diff --git a/docs/src/api/class-error.md b/docs/src/api/class-error.md index 8e797a4add..4f173dada4 100644 --- a/docs/src/api/class-error.md +++ b/docs/src/api/class-error.md @@ -16,11 +16,11 @@ inherit from this class. Message of the error. ## property: Error.name -- returns: <[str]> +- returns: ?<[str]> Name of the error which got thrown inside the browser. Optional. ## property: Error.stack -- returns: <[str]> +- returns: ?<[str]> Stack of the error which got thrown inside the browser. Optional. diff --git a/docs/src/api/class-frame.md b/docs/src/api/class-frame.md index 54beea5ea6..0eb9bb7fe4 100644 --- a/docs/src/api/class-frame.md +++ b/docs/src/api/class-frame.md @@ -352,7 +352,7 @@ await frame.DispatchEventAsync("#source", "dragstart", new { dataTransfer }); DOM event type: `"click"`, `"dragstart"`, etc. ### param: Frame.dispatchEvent.eventInit -- `eventInit` <[EvaluationArgument]> +- `eventInit` ?<[EvaluationArgument]> Optional event-specific initialization properties. @@ -430,7 +430,7 @@ var html = await frame.EvalOnSelectorAsync(".main-container", "(e, suffix) => e. ### param: Frame.evalOnSelector.selector = %%-query-selector-%% ### param: Frame.evalOnSelector.expression = %%-evaluate-expression-%% ### param: Frame.evalOnSelector.arg -- `arg` <[EvaluationArgument]> +- `arg` ?<[EvaluationArgument]> Optional argument to pass to [`param: expression`]. @@ -481,7 +481,7 @@ var divsCount = await frame.EvalOnSelectorAllAsync("div", "(divs, min) => ### param: Frame.evalOnSelectorAll.expression = %%-evaluate-expression-%% ### param: Frame.evalOnSelectorAll.arg -- `arg` <[EvaluationArgument]> +- `arg` ?<[EvaluationArgument]> Optional argument to pass to [`param: expression`]. @@ -587,7 +587,7 @@ await bodyHandle.DisposeAsync(); ### param: Frame.evaluate.expression = %%-evaluate-expression-%% ### param: Frame.evaluate.arg -- `arg` <[EvaluationArgument]> +- `arg` ?<[EvaluationArgument]> Optional argument to pass to [`param: expression`]. @@ -689,7 +689,7 @@ await resultHandle.DisposeAsync(); ### param: Frame.evaluateHandle.expression = %%-evaluate-expression-%% ### param: Frame.evaluateHandle.arg -- `arg` <[EvaluationArgument]> +- `arg` ?<[EvaluationArgument]> Optional argument to pass to [`param: expression`]. @@ -1445,7 +1445,7 @@ await page.MainFrame.WaitForFunctionAsync("selector => !!document.querySelector( ### param: Frame.waitForFunction.expression = %%-evaluate-expression-%% ### param: Frame.waitForFunction.arg -- `arg` <[EvaluationArgument]> +- `arg` ?<[EvaluationArgument]> Optional argument to pass to [`param: expression`]. diff --git a/docs/src/api/class-jshandle.md b/docs/src/api/class-jshandle.md index 026166fda3..3f56c2d6e5 100644 --- a/docs/src/api/class-jshandle.md +++ b/docs/src/api/class-jshandle.md @@ -83,7 +83,7 @@ Assert.AreEqual("10 retweets", await tweetHandle.EvaluateAsync("node => node.inn ### param: JSHandle.evaluate.expression = %%-evaluate-expression-%% ### param: JSHandle.evaluate.arg -- `arg` <[EvaluationArgument]> +- `arg` ?<[EvaluationArgument]> Optional argument to pass to [`param: expression`]. @@ -104,7 +104,7 @@ See [`method: Page.evaluateHandle`] for more details. ### param: JSHandle.evaluateHandle.expression = %%-evaluate-expression-%% ### param: JSHandle.evaluateHandle.arg -- `arg` <[EvaluationArgument]> +- `arg` ?<[EvaluationArgument]> Optional argument to pass to [`param: expression`]. diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.md index 7bd9b3abe7..ce4d18affd 100644 --- a/docs/src/api/class-locator.md +++ b/docs/src/api/class-locator.md @@ -223,7 +223,7 @@ await element.DispatchEventAsync("dragstart", new Dictionary DOM event type: `"click"`, `"dragstart"`, etc. ### param: Locator.dispatchEvent.eventInit -- `eventInit` <[EvaluationArgument]> +- `eventInit` ?<[EvaluationArgument]> Optional event-specific initialization properties. @@ -294,7 +294,7 @@ Assert.AreEqual("10 retweets", await tweets.EvaluateAsync("node => node.innerTex ### param: Locator.evaluate.expression = %%-evaluate-expression-%% ### param: Locator.evaluate.arg -- `arg` <[EvaluationArgument]> +- `arg` ?<[EvaluationArgument]> Optional argument to pass to [`param: expression`]. @@ -339,7 +339,7 @@ var divsCount = await elements.EvaluateAll("(divs, min) => divs.length >= ### param: Locator.evaluateAll.expression = %%-evaluate-expression-%% ### param: Locator.evaluateAll.arg -- `arg` <[EvaluationArgument]> +- `arg` ?<[EvaluationArgument]> Optional argument to pass to [`param: expression`]. @@ -361,7 +361,7 @@ See [`method: Page.evaluateHandle`] for more details. ### param: Locator.evaluateHandle.expression = %%-evaluate-expression-%% ### param: Locator.evaluateHandle.arg -- `arg` <[EvaluationArgument]> +- `arg` ?<[EvaluationArgument]> Optional argument to pass to [`param: expression`]. diff --git a/docs/src/api/class-logger.md b/docs/src/api/class-logger.md index 159ae99fa0..d7be810a21 100644 --- a/docs/src/api/class-logger.md +++ b/docs/src/api/class-logger.md @@ -52,6 +52,6 @@ message arguments ### param: Logger.log.hints - `hints` <[Object]> - - `color` <[string]> Optional preferred logger color. + - `color` ?<[string]> Optional preferred logger color. optional formatting hints diff --git a/docs/src/api/class-mouse.md b/docs/src/api/class-mouse.md index 31e7009b50..da0d41dff1 100644 --- a/docs/src/api/class-mouse.md +++ b/docs/src/api/class-mouse.md @@ -111,7 +111,7 @@ Dispatches a `mousemove` event. ### option: Mouse.move.steps - `steps` <[int]> -defaults to 1. Sends intermediate `mousemove` events. +Defaults to 1. Sends intermediate `mousemove` events. ## async method: Mouse.up diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md index 26f35e2c5c..9bcf7e1ba5 100644 --- a/docs/src/api/class-page.md +++ b/docs/src/api/class-page.md @@ -587,9 +587,9 @@ The order of evaluation of multiple scripts installed via [`method: BrowserConte ### param: Page.addInitScript.script * langs: js - `script` <[function]|[string]|[Object]> - - `path` <[path]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the + - `path` ?<[path]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. Optional. - - `content` <[string]> Raw script content. Optional. + - `content` ?<[string]> Raw script content. Optional. Script to be evaluated in the page. @@ -601,7 +601,7 @@ Script to be evaluated in all pages in the browser context. ### param: Page.addInitScript.arg * langs: js -- `arg` <[Serializable]> +- `arg` ?<[Serializable]> Optional argument to pass to [`param: script`] (only supported when passing a function). @@ -874,7 +874,7 @@ await page.DispatchEventAsync("#source", "dragstart", new { dataTransfer }); DOM event type: `"click"`, `"dragstart"`, etc. ### param: Page.dispatchEvent.eventInit -- `eventInit` <[EvaluationArgument]> +- `eventInit` ?<[EvaluationArgument]> Optional event-specific initialization properties. @@ -1155,7 +1155,7 @@ Shortcut for main frame's [`method: Frame.evalOnSelector`]. ### param: Page.evalOnSelector.selector = %%-query-selector-%% ### param: Page.evalOnSelector.expression = %%-evaluate-expression-%% ### param: Page.evalOnSelector.arg -- `arg` <[EvaluationArgument]> +- `arg` ?<[EvaluationArgument]> Optional argument to pass to [`param: expression`]. @@ -1202,7 +1202,7 @@ var divsCount = await page.EvalOnSelectorAllAsync("div", "(divs, min) => d ### param: Page.evalOnSelectorAll.selector = %%-query-selector-%% ### param: Page.evalOnSelectorAll.expression = %%-evaluate-expression-%% ### param: Page.evalOnSelectorAll.arg -- `arg` <[EvaluationArgument]> +- `arg` ?<[EvaluationArgument]> Optional argument to pass to [`param: expression`]. @@ -1314,7 +1314,7 @@ Shortcut for main frame's [`method: Frame.evaluate`]. ### param: Page.evaluate.expression = %%-evaluate-expression-%% ### param: Page.evaluate.arg -- `arg` <[EvaluationArgument]> +- `arg` ?<[EvaluationArgument]> Optional argument to pass to [`param: expression`]. @@ -1415,7 +1415,7 @@ await resultHandle.DisposeAsync(); ### param: Page.evaluateHandle.expression = %%-evaluate-expression-%% ### param: Page.evaluateHandle.arg -- `arg` <[EvaluationArgument]> +- `arg` ?<[EvaluationArgument]> Optional argument to pass to [`param: expression`]. @@ -1909,8 +1909,8 @@ var frame = page.FrameByUrl(".*domain.*"); ### param: Page.frame.frameSelector * langs: js - `frameSelector` <[string]|[Object]> - - `name` <[string]> Frame name specified in the `iframe`'s `name` attribute. Optional. - - `url` <[string]|[RegExp]|[function]\([URL]\):[boolean]> A glob pattern, regex pattern or predicate receiving + - `name` ?<[string]> Frame name specified in the `iframe`'s `name` attribute. Optional. + - `url` ?<[string]|[RegExp]|[function]\([URL]\):[boolean]> A glob pattern, regex pattern or predicate receiving frame's `url` as a [URL] object. Optional. Frame name or other frame lookup options. @@ -2387,20 +2387,20 @@ Paper height, accepts values labeled with units. ### option: Page.pdf.margin * langs: js, python - `margin` <[Object]> - - `top` <[string]|[float]> Top margin, accepts values labeled with units. Defaults to `0`. - - `right` <[string]|[float]> Right margin, accepts values labeled with units. Defaults to `0`. - - `bottom` <[string]|[float]> Bottom margin, accepts values labeled with units. Defaults to `0`. - - `left` <[string]|[float]> Left margin, accepts values labeled with units. Defaults to `0`. + - `top` ?<[string]|[float]> Top margin, accepts values labeled with units. Defaults to `0`. + - `right` ?<[string]|[float]> Right margin, accepts values labeled with units. Defaults to `0`. + - `bottom` ?<[string]|[float]> Bottom margin, accepts values labeled with units. Defaults to `0`. + - `left` ?<[string]|[float]> Left margin, accepts values labeled with units. Defaults to `0`. Paper margins, defaults to none. ### option: Page.pdf.margin * langs: csharp, java - `margin` <[Object]> - - `top` <[string]> Top margin, accepts values labeled with units. Defaults to `0`. - - `right` <[string]> Right margin, accepts values labeled with units. Defaults to `0`. - - `bottom` <[string]> Bottom margin, accepts values labeled with units. Defaults to `0`. - - `left` <[string]> Left margin, accepts values labeled with units. Defaults to `0`. + - `top` ?<[string]> Top margin, accepts values labeled with units. Defaults to `0`. + - `right` ?<[string]> Right margin, accepts values labeled with units. Defaults to `0`. + - `bottom` ?<[string]> Bottom margin, accepts values labeled with units. Defaults to `0`. + - `left` ?<[string]> Left margin, accepts values labeled with units. Defaults to `0`. Paper margins, defaults to none. @@ -3103,13 +3103,13 @@ A glob pattern, regex pattern or predicate receiving [URL] to match while routin ### param: Page.unroute.handler * langs: js, python -- `handler` <[function]\([Route], [Request]\)> +- `handler` ?<[function]\([Route], [Request]\)> Optional handler function to route the request. ### param: Page.unroute.handler * langs: csharp, java -- `handler` <[function]\([Route]\)> +- `handler` ?<[function]\([Route]\)> Optional handler function to route the request. @@ -3205,9 +3205,9 @@ frame = event_info.value ### param: Page.waitForEvent.optionsOrPredicate * langs: js -- `optionsOrPredicate` <[function]|[Object]> +- `optionsOrPredicate` ?<[function]|[Object]> - `predicate` <[function]> receives the event data and resolves to truthy value when the waiting should resolve. - - `timeout` <[float]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to + - `timeout` ?<[float]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [`method: BrowserContext.setDefaultTimeout`]. Either a predicate that receives an event or an options object. Optional. @@ -3348,7 +3348,7 @@ Shortcut for main frame's [`method: Frame.waitForFunction`]. ### param: Page.waitForFunction.expression = %%-evaluate-expression-%% ### param: Page.waitForFunction.arg -- `arg` <[EvaluationArgument]> +- `arg` ?<[EvaluationArgument]> Optional argument to pass to [`param: expression`]. diff --git a/docs/src/api/class-response.md b/docs/src/api/class-response.md index 6dd0c7da4c..5ff51e6098 100644 --- a/docs/src/api/class-response.md +++ b/docs/src/api/class-response.md @@ -84,14 +84,14 @@ Returns the matching [Request] object. ## async method: Response.securityDetails - returns: <[null]|[Object]> - - `issuer` <[string]> Common Name component of the Issuer field. + - `issuer` ?<[string]> Common Name component of the Issuer field. from the certificate. This should only be used for informational purposes. Optional. - - `protocol` <[string]> The specific TLS protocol used. (e.g. `TLS 1.3`). Optional. - - `subjectName` <[string]> Common Name component of the Subject + - `protocol` ?<[string]> The specific TLS protocol used. (e.g. `TLS 1.3`). Optional. + - `subjectName` ?<[string]> Common Name component of the Subject field from the certificate. This should only be used for informational purposes. Optional. - - `validFrom` <[float]> Unix timestamp (in seconds) specifying + - `validFrom` ?<[float]> Unix timestamp (in seconds) specifying when this cert becomes valid. Optional. - - `validTo` <[float]> Unix timestamp (in seconds) specifying + - `validTo` ?<[float]> Unix timestamp (in seconds) specifying when this cert becomes invalid. Optional. Returns SSL and other security information. diff --git a/docs/src/api/class-route.md b/docs/src/api/class-route.md index 61dd9e3ad4..d1002c5da1 100644 --- a/docs/src/api/class-route.md +++ b/docs/src/api/class-route.md @@ -8,7 +8,7 @@ allows to handle the route. Aborts the route's request. ### param: Route.abort.errorCode -- `errorCode` <[string]> +- `errorCode` ?<[string]> Optional error code. Defaults to `failed`, could be one of the following: * `'aborted'` - An operation was aborted (due to user action) @@ -154,7 +154,7 @@ page.route("**/*", lambda route: route.fulfill( ```csharp await page.RouteAsync("**/*", route => route.FulfillAsync( status: 404, - contentType: "text/plain", + contentType: "text/plain", body: "Not Found!")); ``` diff --git a/docs/src/api/class-selectors.md b/docs/src/api/class-selectors.md index 37d5c5c78b..60332f867e 100644 --- a/docs/src/api/class-selectors.md +++ b/docs/src/api/class-selectors.md @@ -176,9 +176,9 @@ contain `[a-zA-Z0-9_]` characters. ### param: Selectors.register.script * langs: js - `script` <[function]|[string]|[Object]> - - `path` <[path]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the + - `path` ?<[path]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. Optional. - - `content` <[string]> Raw script content. Optional. + - `content` ?<[string]> Raw script content. Optional. Script that evaluates to a selector engine instance. diff --git a/docs/src/api/class-websocket.md b/docs/src/api/class-websocket.md index 26e31799c8..13a3e5e071 100644 --- a/docs/src/api/class-websocket.md +++ b/docs/src/api/class-websocket.md @@ -57,9 +57,9 @@ Event name, same one would pass into `webSocket.on(event)`. ### param: WebSocket.waitForEvent.optionsOrPredicate * langs: js -- `optionsOrPredicate` <[function]|[Object]> +- `optionsOrPredicate` ?<[function]|[Object]> - `predicate` <[function]> receives the event data and resolves to truthy value when the waiting should resolve. - - `timeout` <[float]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [`method: BrowserContext.setDefaultTimeout`]. + - `timeout` ?<[float]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [`method: BrowserContext.setDefaultTimeout`]. Either a predicate that receives an event or an options object. Optional. diff --git a/docs/src/api/class-worker.md b/docs/src/api/class-worker.md index 121c1c8103..c29bf21999 100644 --- a/docs/src/api/class-worker.md +++ b/docs/src/api/class-worker.md @@ -70,7 +70,7 @@ additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, ### param: Worker.evaluate.expression = %%-evaluate-expression-%% ### param: Worker.evaluate.arg -- `arg` <[EvaluationArgument]> +- `arg` ?<[EvaluationArgument]> Optional argument to pass to [`param: expression`]. @@ -89,7 +89,7 @@ the promise to resolve and return its value. ### param: Worker.evaluateHandle.expression = %%-evaluate-expression-%% ### param: Worker.evaluateHandle.arg -- `arg` <[EvaluationArgument]> +- `arg` ?<[EvaluationArgument]> Optional argument to pass to [`param: expression`]. diff --git a/docs/src/api/params.md b/docs/src/api/params.md index 2b0f77a357..cf58f584d8 100644 --- a/docs/src/api/params.md +++ b/docs/src/api/params.md @@ -186,10 +186,10 @@ Dangerous option; use with care. Defaults to `false`. - `server` <[string]> Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example `http://myproxy.com:3128` or `socks5://myproxy.com:3128`. Short form `myproxy.com:3128` is considered an HTTP proxy. - - `bypass` <[string]> Optional comma-separated domains to bypass proxy, for example `".com, chromium.org, + - `bypass` ?<[string]> Optional comma-separated domains to bypass proxy, for example `".com, chromium.org, .domain.com"`. - - `username` <[string]> Optional username to use if HTTP proxy requires authentication. - - `password` <[string]> Optional password to use if HTTP proxy requires authentication. + - `username` ?<[string]> Optional username to use if HTTP proxy requires authentication. + - `password` ?<[string]> Optional password to use if HTTP proxy requires authentication. Network proxy settings. @@ -456,7 +456,7 @@ for a list of supported timezone IDs. - `geolocation` <[Object]> - `latitude` <[float]> Latitude between -90 and 90. - `longitude` <[float]> Longitude between -180 and 180. - - `accuracy` <[float]> Non-negative accuracy value. Defaults to `0`. + - `accuracy` ?<[float]> Non-negative accuracy value. Defaults to `0`. ## context-option-locale - `locale` <[string]> @@ -532,7 +532,7 @@ Logger sink for Playwright logging. ## context-option-recordhar * langs: js - `recordHar` <[Object]> - - `omitContent` <[boolean]> Optional setting to control whether to omit request content from the HAR. Defaults to + - `omitContent` ?<[boolean]> Optional setting to control whether to omit request content from the HAR. Defaults to `false`. - `path` <[path]> Path on the filesystem to write the HAR file to. @@ -560,7 +560,7 @@ Optional setting to control whether to omit request content from the HAR. Defaul * langs: js - `recordVideo` <[Object]> - `dir` <[path]> Path to the directory to put videos into. - - `size` <[Object]> Optional dimensions of the recorded videos. If not specified the size will be equal to `viewport` + - `size` ?<[Object]> Optional dimensions of the recorded videos. If not specified the size will be equal to `viewport` scaled down to fit into 800x800. If `viewport` is not configured explicitly the video size defaults to 800x450. Actual picture of each page will be scaled down if necessary to fit the specified size. - `width` <[int]> Video frame width. @@ -594,9 +594,9 @@ Actual picture of each page will be scaled down if necessary to fit the specifie - `proxy` <[Object]> - `server` <[string]> Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example `http://myproxy.com:3128` or `socks5://myproxy.com:3128`. Short form `myproxy.com:3128` is considered an HTTP proxy. - - `bypass` <[string]> Optional comma-separated domains to bypass proxy, for example `".com, chromium.org, .domain.com"`. - - `username` <[string]> Optional username to use if HTTP proxy requires authentication. - - `password` <[string]> Optional password to use if HTTP proxy requires authentication. + - `bypass` ?<[string]> Optional comma-separated domains to bypass proxy, for example `".com, chromium.org, .domain.com"`. + - `username` ?<[string]> Optional username to use if HTTP proxy requires authentication. + - `password` ?<[string]> Optional password to use if HTTP proxy requires authentication. Network proxy settings to use with this context. @@ -616,9 +616,9 @@ See [Locator] to learn more about the strict mode. ## select-options-values * langs: java, js, csharp - `values` <[null]|[string]|[ElementHandle]|[Array]<[string]>|[Object]|[Array]<[ElementHandle]>|[Array]<[Object]>> - - `value` <[string]> Matches by `option.value`. Optional. - - `label` <[string]> Matches by `option.label`. Optional. - - `index` <[int]> Matches by the index. Optional. + - `value` ?<[string]> Matches by `option.value`. Optional. + - `label` ?<[string]> Matches by `option.label`. Optional. + - `index` ?<[int]> Matches by the index. Optional. Options to select. If the `` has the `multiple` attribute, all given options are selected, otherwise only the first option matching one of the passed options is selected. Optional. ## python-select-options-label * langs: python -- `label` <[string]|[Array]<[string]>> +- `label` ?<[string]|[Array]<[string]>> Options to select by label. If the `