mirror of
https://github.com/microsoft/playwright.git
synced 2024-10-27 21:58:52 +03:00
docs: explicitly annotate methods and parameters (#4771)
This commit is contained in:
parent
c81ec9ccca
commit
2e220df7ac
File diff suppressed because it is too large
Load Diff
@ -77,7 +77,7 @@ This object can be used to launch or connect to Chromium, returning instances of
|
||||
#### playwright.devices
|
||||
- returns: <[Object]>
|
||||
|
||||
Returns a list of devices to be used with [`browser.newContext([options])`](#browsernewcontextoptions) or [`browser.newPage([options])`](#browsernewpageoptions). Actual list of devices can be found in [src/server/deviceDescriptors.ts](https://github.com/Microsoft/playwright/blob/master/src/server/deviceDescriptors.ts).
|
||||
Returns a list of devices to be used with [`method: Browser.newContext`]() or [`method: Browser.newPage`](). Actual list of devices can be found in [src/server/deviceDescriptors.ts](https://github.com/Microsoft/playwright/blob/master/src/server/deviceDescriptors.ts).
|
||||
|
||||
```js
|
||||
const { webkit, devices } = require('playwright');
|
||||
@ -99,7 +99,7 @@ const iPhone = devices['iPhone 6'];
|
||||
- returns: <[Object]>
|
||||
- `TimeoutError` <[function]> A class of [TimeoutError].
|
||||
|
||||
Playwright methods might throw errors if they are unable to fulfill a request. For example, [page.waitForSelector(selector[, options])](#pagewaitforselectorselector-options)
|
||||
Playwright methods might throw errors if they are unable to fulfill a request. For example, [`method: Page.waitForSelector`]()
|
||||
might fail if the selector doesn't match any nodes during the given timeframe.
|
||||
|
||||
For certain types of errors Playwright uses specific error classes.
|
||||
|
@ -13,25 +13,25 @@ When to consider operation succeeded, defaults to `load`. Events can be either:
|
||||
|
||||
Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout.
|
||||
The default value can be changed by using the
|
||||
[browserContext.setDefaultNavigationTimeout()](),
|
||||
[browserContext.setDefaultTimeout()](),
|
||||
[page.setDefaultNavigationTimeout()]() or
|
||||
[page.setDefaultTimeout()]() methods.
|
||||
[`method: BrowserContext.setDefaultNavigationTimeout`](),
|
||||
[`method: BrowserContext.setDefaultTimeout`](),
|
||||
[`method: Page.setDefaultNavigationTimeout`]() or
|
||||
[`method: Page.setDefaultTimeout`]() methods.
|
||||
|
||||
## wait-for-timeout
|
||||
|
||||
- `timeout` <[number]>
|
||||
|
||||
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 [browserContext.setDefaultTimeout()]().
|
||||
value can be changed by using the [`method: BrowserContext.setDefaultTimeout`]().
|
||||
|
||||
## input-timeout
|
||||
|
||||
- `timeout` <[number]>
|
||||
|
||||
Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by
|
||||
using the [browserContext.setDefaultTimeout()]() or
|
||||
[page.setDefaultTimeout()]() methods.
|
||||
using the [`method: BrowserContext.setDefaultTimeout`]() or
|
||||
[`method: Page.setDefaultTimeout`]() methods.
|
||||
|
||||
## input-no-wait-after
|
||||
|
||||
@ -133,7 +133,7 @@ Defaults to `'visible'`. Can be either:
|
||||
- `value` <[string]>
|
||||
|
||||
Populates context with given storage state. This method can be used to initialize context with logged-in information
|
||||
obtained via [browserContext.storageState()](). Either a path to the file with saved storage, or an object with the following fields:
|
||||
obtained via [`method: BrowserContext.storageState`](). Either a path to the file with saved storage, or an object with the following fields:
|
||||
|
||||
## context-option-acceptdownloads
|
||||
|
||||
@ -218,7 +218,7 @@ request header value as well as number and date formatting rules.
|
||||
- `permissions` <[Array]<[string]>>
|
||||
|
||||
A list of permissions to grant to all pages in this context. See
|
||||
[browserContext.grantPermissions()]() for more details.
|
||||
[`method: BrowserContext.grantPermissions`]() for more details.
|
||||
|
||||
## context-option-extrahttpheaders
|
||||
|
||||
@ -245,7 +245,7 @@ Credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/W
|
||||
- `colorScheme` <"light"|"dark"|"no-preference">
|
||||
|
||||
Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See
|
||||
[page.emulateMedia()]() for more details. Defaults to '`light`'.
|
||||
[`method: Page.emulateMedia`]() for more details. Defaults to '`light`'.
|
||||
|
||||
## context-option-logger
|
||||
|
||||
@ -257,9 +257,9 @@ Logger sink for Playwright logging.
|
||||
|
||||
- `videosPath` <[string]>
|
||||
|
||||
**NOTE** Use `recordVideo` instead, it takes precedence over `videosPath`. Enables video recording for all pages to
|
||||
**NOTE** Use [`param: recordVideo`]() instead, it takes precedence over `videosPath`. Enables video recording for all pages to
|
||||
`videosPath` directory. If not specified, videos are not recorded. Make sure to await
|
||||
[browserContext.close()]() for videos to be saved.
|
||||
[`method: BrowserContext.close`]() for videos to be saved.
|
||||
|
||||
## context-option-videosize
|
||||
|
||||
@ -267,7 +267,7 @@ Logger sink for Playwright logging.
|
||||
- `width` <[number]> Video frame width.
|
||||
- `height` <[number]> Video frame height.
|
||||
|
||||
**NOTE** Use `recordVideo` instead, it takes precedence over `videoSize`. Specifies dimensions of the automatically
|
||||
**NOTE** Use [`param: recordVideo`]() instead, it takes precedence over `videoSize`. Specifies dimensions of the automatically
|
||||
recorded video. Can only be used if `videosPath` is set. If not specified the size will be equal to `viewport`. If
|
||||
`viewport` is not configured explicitly the video size defaults to 1280x720. Actual picture of the page will be scaled
|
||||
down if necessary to fit specified size.
|
||||
@ -280,7 +280,7 @@ down if necessary to fit specified size.
|
||||
- `path` <[string]> Path on the filesystem to write the HAR file to.
|
||||
|
||||
Enables [HAR](http://www.softwareishard.com/blog/har-12-spec) recording for all pages into `recordHar.path` file. If not
|
||||
specified, the HAR is not recorded. Make sure to await [browserContext.close()]() for the HAR to be
|
||||
specified, the HAR is not recorded. Make sure to await [`method: BrowserContext.close`]() for the HAR to be
|
||||
saved.
|
||||
|
||||
## context-option-recordvideo
|
||||
@ -294,7 +294,7 @@ saved.
|
||||
- `height` <[number]> Video frame height.
|
||||
|
||||
Enables video recording for all pages into `recordVideo.dir` directory. If not specified videos are not recorded. Make
|
||||
sure to await [browserContext.close()]() for videos to be saved.
|
||||
sure to await [`method: BrowserContext.close`]() for videos to be saved.
|
||||
|
||||
## context-option-proxy
|
||||
|
||||
|
1071
docs/api.md
1071
docs/api.md
File diff suppressed because it is too large
Load Diff
@ -199,7 +199,7 @@ async function run() {
|
||||
}
|
||||
}
|
||||
}
|
||||
api.setText([comment, header, renderMd(nodes), footer].join('\n'));
|
||||
api.setText([comment, header, renderMd(nodes, 10000), footer].join('\n'));
|
||||
|
||||
// Generate links
|
||||
preprocessor.generateLinks(api, signatures, messages);
|
||||
|
@ -188,22 +188,32 @@ function generateLinks(source, signatures, messages) {
|
||||
let match;
|
||||
while (match = linkRegex.exec(line)) {
|
||||
const [, name] = match;
|
||||
const linkOffset = offset + lineNumber + match.index;
|
||||
const hrefOffset = offset + lineNumber + match.index + 3 + name.length;
|
||||
const eventMatch = name.match(/.*on\('.*'\)/);
|
||||
let replacement;
|
||||
if (eventMatch) {
|
||||
replacement = eventMatch[0];
|
||||
} else {
|
||||
const method = name.substring(0, name.length - 2);
|
||||
const memberMatch = name.match(/`(event|method|namespace):\s(JS|CDP|[A-Z])([^.]+)\.(.*)`/m);
|
||||
const paramMatch = name.match(/`(?:param|option):\s(.*)`/m);
|
||||
if (!memberMatch && !paramMatch) {
|
||||
messages.push(Message.error(`Bad link: ${source.filePath()}:${lineNumber + 1}: ${name}`));
|
||||
return;
|
||||
}
|
||||
if (memberMatch && memberMatch[1] === 'event') {
|
||||
replacement = `${memberMatch[2].toLowerCase() + memberMatch[3]}.on('${memberMatch[4]}')`;
|
||||
sourceEdits.edit(linkOffset + 1, hrefOffset - 2, replacement);
|
||||
} else if (memberMatch && memberMatch[1] === 'method') {
|
||||
const method = memberMatch[2].toLowerCase() + memberMatch[3] + '.' + memberMatch[4];
|
||||
let signature = signatures.get(method);
|
||||
if (signature === undefined) {
|
||||
messages.push(Message.error(`Bad method link: ${source.filePath()}:${lineNumber + 1}: ${method}`));
|
||||
signature = '\u2026';
|
||||
signature = '(\u2026)';
|
||||
}
|
||||
sourceEdits.edit(hrefOffset - 3, hrefOffset - 3, signature);
|
||||
replacement = name + signature;
|
||||
replacement = method + '(' + signature + ')';
|
||||
sourceEdits.edit(linkOffset + 2, hrefOffset - 3, replacement);
|
||||
} else if (paramMatch) {
|
||||
sourceEdits.edit(linkOffset, hrefOffset + 1, '`' + paramMatch[1] + '`');
|
||||
}
|
||||
sourceEdits.edit(hrefOffset, hrefOffset, '#' + replacement.toLowerCase().replace(/[^a-z]/gm, ''));
|
||||
if (replacement)
|
||||
sourceEdits.edit(hrefOffset, hrefOffset, '#' + replacement.toLowerCase().replace(/[^a-z]/gm, ''));
|
||||
}
|
||||
offset += line.length;
|
||||
});
|
||||
|
@ -14,8 +14,6 @@
|
||||
* limitations under the License.
|
||||
*/
|
||||
|
||||
const maxColumns = 120;
|
||||
|
||||
function normalizeLines(content) {
|
||||
const inLines = content.split('\n');
|
||||
let inCodeBlock = false;
|
||||
@ -133,23 +131,17 @@ function parseMd(content) {
|
||||
return buildTree(normalizeLines(content));
|
||||
}
|
||||
|
||||
function renderMd(nodes) {
|
||||
function renderMd(nodes, maxColumns) {
|
||||
const result = [];
|
||||
let lastNode;
|
||||
for (let node of nodes) {
|
||||
innerRenderMdNode(node, lastNode, result);
|
||||
innerRenderMdNode(node, lastNode, result, maxColumns);
|
||||
lastNode = node;
|
||||
}
|
||||
return result.join('\n');
|
||||
}
|
||||
|
||||
function renderMdNode(node, lastNode) {
|
||||
const result = [];
|
||||
innerRenderMdNode(node, lastNode, result);
|
||||
return result.join('\n');
|
||||
}
|
||||
|
||||
function innerRenderMdNode(node, lastNode, result) {
|
||||
function innerRenderMdNode(node, lastNode, result, maxColumns = 120) {
|
||||
const newLine = () => {
|
||||
if (result[result.length - 1] !== '')
|
||||
result.push('');
|
||||
@ -161,7 +153,7 @@ function innerRenderMdNode(node, lastNode, result) {
|
||||
result.push(`${'#'.repeat(i)} ${node[`h${i}`]}`);
|
||||
let lastNode = node;
|
||||
for (const child of node.children) {
|
||||
innerRenderMdNode(child, lastNode, result);
|
||||
innerRenderMdNode(child, lastNode, result, maxColumns);
|
||||
lastNode = child;
|
||||
}
|
||||
break;
|
||||
@ -172,7 +164,7 @@ function innerRenderMdNode(node, lastNode, result) {
|
||||
const bothComments = node.text.startsWith('>') && lastNode && lastNode.text && lastNode.text.startsWith('>');
|
||||
if (!bothComments && lastNode && (lastNode.text || lastNode.li || lastNode.h1 || lastNode.h2 || lastNode.h3 || lastNode.h4))
|
||||
newLine();
|
||||
printText(node, result);
|
||||
printText(node, result, maxColumns);
|
||||
}
|
||||
|
||||
if (node.code) {
|
||||
@ -207,7 +199,7 @@ function innerRenderMdNode(node, lastNode, result) {
|
||||
}
|
||||
}
|
||||
|
||||
function printText(node, result) {
|
||||
function printText(node, result, maxColumns) {
|
||||
let line = node.text;
|
||||
while (line.length > maxColumns) {
|
||||
let index = line.lastIndexOf(' ', maxColumns);
|
||||
|
Loading…
Reference in New Issue
Block a user