yujunjun/playwright
1
0
Fork 0
mirror of https://github.com/microsoft/playwright.git synced 2025-06-26 21:40:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: make inline refs us parameter name instead of its alias (#5219)

Browse Source
This commit is contained in:
Yury Semikhatsky 2021-01-29 16:02:17 -08:00 committed by GitHub
parent 975519150e
commit a1d875ed97
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 80 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
docs/src/api/class-elementhandle.md
View File

@ -247,13 +247,13 @@ Optional event-specific initialization properties.
- alias-js: $eval
- returns: <[Serializable]>
Returns the return value of [`param: pageFunction`]
Returns the return value of [`param: expression`]
The method finds an element matching the specified selector in the `ElementHandle`s subtree and passes it as a first
argument to [`param: pageFunction`]. See [Working with selectors](./selectors.md) for more
argument to [`param: expression`]. See [Working with selectors](./selectors.md) for more
details. If no elements match the selector, the method throws an error.
If [`param: pageFunction`] returns a [Promise], then [`method: ElementHandle.evalOnSelector`] would wait for the promise to resolve and return its
If [`param: expression`] returns a [Promise], then [`method: ElementHandle.evalOnSelector`] would wait for the promise to resolve and return its
value.
Examples:
@ -283,7 +283,7 @@ assert tweet_handle.eval_on_selector(".retweets", "node => node.innerText") = "1
### param: ElementHandle.evalOnSelector.arg
- `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`]
Optional argument to pass to [`param: expression`]
## async method: ElementHandle.evalOnSelectorAll
* langs:
@ -291,13 +291,13 @@ Optional argument to pass to [`param: pageFunction`]
- alias-js: $$eval
- returns: <[Serializable]>
Returns the return value of [`param: pageFunction`]
Returns the return value of [`param: expression`]
The method finds all elements matching the specified selector in the `ElementHandle`'s subtree and passes an array of
matched elements as a first argument to [`param: pageFunction`]. See
matched elements as a first argument to [`param: expression`]. See
[Working with selectors](./selectors.md) for more details.
If [`param: pageFunction`] returns a [Promise], then [`method: ElementHandle.evalOnSelectorAll`] would wait for the promise to resolve and return its
If [`param: expression`] returns a [Promise], then [`method: ElementHandle.evalOnSelectorAll`] would wait for the promise to resolve and return its
value.
Examples:
@ -331,7 +331,7 @@ assert feed_handle.eval_on_selector_all(".tweet", "nodes => nodes.map(n => n.inn
### param: ElementHandle.evalOnSelectorAll.arg
- `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`]
Optional argument to pass to [`param: expression`]
## async method: ElementHandle.fill

30
docs/src/api/class-frame.md
View File

@ -300,13 +300,13 @@ Optional event-specific initialization properties.
- alias-js: $eval
- returns: <[Serializable]>
Returns the return value of [`param: pageFunction`]
Returns the return value of [`param: expression`]
The method finds an element matching the specified selector within the frame and passes it as a first argument to
[`param: pageFunction`]. See [Working with selectors](./selectors.md) for more details. If no
[`param: expression`]. See [Working with selectors](./selectors.md) for more details. If no
elements match the selector, the method throws an error.
If [`param: pageFunction`] returns a [Promise], then [`method: Frame.evalOnSelector`] would wait for the promise to resolve and return its
If [`param: expression`] returns a [Promise], then [`method: Frame.evalOnSelector`] would wait for the promise to resolve and return its
value.
Examples:
@ -336,7 +336,7 @@ html = frame.eval_on_selector(".main-container", "(e, suffix) => e.outerHTML + s
### param: Frame.evalOnSelector.arg
- `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`]
Optional argument to pass to [`param: expression`]
## async method: Frame.evalOnSelectorAll
* langs:
@ -344,13 +344,13 @@ Optional argument to pass to [`param: pageFunction`]
- alias-js: $$eval
- returns: <[Serializable]>
Returns the return value of [`param: pageFunction`]
Returns the return value of [`param: expression`]
The method finds all elements matching the specified selector within the frame and passes an array of matched elements
as a first argument to [`param: pageFunction`]. See [Working with selectors](./selectors.md) for
as a first argument to [`param: expression`]. See [Working with selectors](./selectors.md) for
more details.
If [`param: pageFunction`] returns a [Promise], then [`method: Frame.evalOnSelectorAll`] would wait for the promise to resolve and return its
If [`param: expression`] returns a [Promise], then [`method: Frame.evalOnSelectorAll`] would wait for the promise to resolve and return its
value.
Examples:
@ -374,12 +374,12 @@ divs_counts = frame.eval_on_selector_all("div", "(divs, min) => divs.length >= m
### param: Frame.evalOnSelectorAll.arg
- `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`]
Optional argument to pass to [`param: expression`]
## async method: Frame.evaluate
- returns: <[Serializable]>
Returns the return value of [`param: pageFunction`]
Returns the return value of [`param: expression`]
If the function passed to the [`method: Frame.evaluate`] returns a [Promise], then [`method: Frame.evaluate`] would wait for the promise to
resolve and return its value.
@ -450,12 +450,12 @@ body_handle.dispose()
### param: Frame.evaluate.arg
- `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`]
Optional argument to pass to [`param: expression`]
## async method: Frame.evaluateHandle
- returns: <[JSHandle]>
Returns the return value of [`param: pageFunction`] as in-page object (JSHandle).
Returns the return value of [`param: expression`] as in-page object (JSHandle).
The only difference between [`method: Frame.evaluate`] and [`method: Frame.evaluateHandle`] is that
[method: Frame.evaluateHandle`] returns in-page object (JSHandle).
@ -520,7 +520,7 @@ result_handle.dispose()
### param: Frame.evaluateHandle.arg
- `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`]
Optional argument to pass to [`param: expression`]
## async method: Frame.fill
@ -1010,7 +1010,7 @@ Returns frame's url.
## async method: Frame.waitForFunction
- returns: <[JSHandle]>
Returns when the [`param: pageFunction`] returns a truthy value, returns that value.
Returns when the [`param: expression`] returns a truthy value, returns that value.
The [`method: Frame.waitForFunction`] can be used to observe viewport size change:
@ -1082,12 +1082,12 @@ frame.wait_for_function("selector => !!document.querySelector(selector)", select
### param: Frame.waitForFunction.arg
- `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`]
Optional argument to pass to [`param: expression`]
### option: Frame.waitForFunction.polling
- `polling` <[float]|"raf">
If [`option: polling`] is `'raf'`, then [`param: pageFunction`] is constantly executed in `requestAnimationFrame`
If [`option: polling`] is `'raf'`, then [`param: expression`] is constantly executed in `requestAnimationFrame`
callback. If [`option: polling`] is a number, then it is treated as an interval in milliseconds at which the function
would be executed. Defaults to `raf`.

14
docs/src/api/class-jshandle.md
View File

@ -37,11 +37,11 @@ The `jsHandle.dispose` method stops referencing the element handle.
## async method: JSHandle.evaluate
- returns: <[Serializable]>
Returns the return value of [`param: pageFunction`]
Returns the return value of [`param: expression`]
This method passes this handle as the first argument to [`param: pageFunction`].
This method passes this handle as the first argument to [`param: expression`].
If [`param: pageFunction`] returns a [Promise], then `handle.evaluate` would wait for the promise to resolve and return
If [`param: expression`] returns a [Promise], then `handle.evaluate` would wait for the promise to resolve and return
its value.
Examples:
@ -66,14 +66,14 @@ assert tweet_handle.evaluate("node => node.innerText") == "10 retweets"
### param: JSHandle.evaluate.arg
- `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`]
Optional argument to pass to [`param: expression`]
## async method: JSHandle.evaluateHandle
- returns: <[JSHandle]>
Returns the return value of [`param: pageFunction`] as in-page object (JSHandle).
Returns the return value of [`param: expression`] as in-page object (JSHandle).
This method passes this handle as the first argument to [`param: pageFunction`].
This method passes this handle as the first argument to [`param: expression`].
The only difference between `jsHandle.evaluate` and `jsHandle.evaluateHandle` is that `jsHandle.evaluateHandle` returns
in-page object (JSHandle).
@ -88,7 +88,7 @@ See [`method: Page.evaluateHandle`] for more details.
### param: JSHandle.evaluateHandle.arg
- `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`]
Optional argument to pass to [`param: expression`]
## async method: JSHandle.getProperties
- returns: <[Map]<[string], [JSHandle]>>

30
docs/src/api/class-page.md
View File

@ -727,10 +727,10 @@ Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`
- returns: <[Serializable]>
The method finds an element matching the specified selector within the page and passes it as a first argument to
[`param: pageFunction`]. If no elements match the selector, the method throws an error. Returns the value of
[`param: pageFunction`].
[`param: expression`]. If no elements match the selector, the method throws an error. Returns the value of
[`param: expression`].
If [`param: pageFunction`] returns a [Promise], then [`method: Page.evalOnSelector`] would wait for the promise to resolve and
If [`param: expression`] returns a [Promise], then [`method: Page.evalOnSelector`] would wait for the promise to resolve and
return its value.
Examples:
@ -762,7 +762,7 @@ Shortcut for main frame's [`method: Frame.evalOnSelector`].
### param: Page.evalOnSelector.arg
- `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`]
Optional argument to pass to [`param: expression`]
## async method: Page.evalOnSelectorAll
* langs:
@ -771,9 +771,9 @@ Optional argument to pass to [`param: pageFunction`]
- 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 [`param: pageFunction`]. Returns the result of [`param: pageFunction`] invocation.
a first argument to [`param: expression`]. Returns the result of [`param: expression`] invocation.
If [`param: pageFunction`] returns a [Promise], then [`method: Page.evalOnSelectorAll`] would wait for the promise to resolve and
If [`param: expression`] returns a [Promise], then [`method: Page.evalOnSelectorAll`] would wait for the promise to resolve and
return its value.
Examples:
@ -797,12 +797,12 @@ div_counts = page.eval_on_selector_all("div", "(divs, min) => divs.length >= min
### param: Page.evalOnSelectorAll.arg
- `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`]
Optional argument to pass to [`param: expression`]
## async method: Page.evaluate
- returns: <[Serializable]>
Returns the value of the [`param: pageFunction`] invocation.
Returns the value of the [`param: expression`] invocation.
If the function passed to the [`method: Page.evaluate`] returns a [Promise], then [`method: Page.evaluate`] would wait
for the promise to resolve and return its value.
@ -811,7 +811,7 @@ If the function passed to the [`method: Page.evaluate`] returns a non-[Serializa
[`method: Page.evaluate`] resolves to `undefined`. DevTools Protocol also supports transferring some additional values
that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals.
Passing argument to [`param: pageFunction`]:
Passing argument to [`param: expression`]:
```js
const result = await page.evaluate(([x, y]) => {
@ -877,12 +877,12 @@ Shortcut for main frame's [`method: Frame.evaluate`].
### param: Page.evaluate.arg
- `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`]
Optional argument to pass to [`param: expression`]
## async method: Page.evaluateHandle
- returns: <[JSHandle]>
Returns the value of the [`param: pageFunction`] invocation as in-page object (JSHandle).
Returns the value of the [`param: expression`] invocation as in-page object (JSHandle).
The only difference between [`method: Page.evaluate`] and [`method: Page.evaluateHandle`] is that [`method: Page.evaluateHandle`] returns in-page
object (JSHandle).
@ -947,7 +947,7 @@ result_handle.dispose()
### param: Page.evaluateHandle.arg
- `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`]
Optional argument to pass to [`param: expression`]
## async method: Page.exposeBinding
@ -2197,7 +2197,7 @@ Either a predicate that receives an event or an options object. Optional.
## async method: Page.waitForFunction
- returns: <[JSHandle]>
Returns when the [`param: pageFunction`] returns a truthy value. It resolves to a JSHandle of the truthy value.
Returns when the [`param: expression`] returns a truthy value. It resolves to a JSHandle of the truthy value.
The [`method: Page.waitForFunction`] can be used to observe viewport size change:
@ -2271,12 +2271,12 @@ Shortcut for main frame's [`method: Frame.waitForFunction`].
### param: Page.waitForFunction.arg
- `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`]
Optional argument to pass to [`param: expression`]
### option: Page.waitForFunction.polling
- `polling` <[float]|"raf">
If [`option: polling`] is `'raf'`, then [`param: pageFunction`] is constantly executed in `requestAnimationFrame`
If [`option: polling`] is `'raf'`, then [`param: expression`] is constantly executed in `requestAnimationFrame`
callback. If [`option: polling`] is a number, then it is treated as an interval in milliseconds at which the function
would be executed. Defaults to `raf`.

8
docs/src/api/class-worker.md
View File

@ -35,7 +35,7 @@ Emitted when this dedicated [WebWorker](https://developer.mozilla.org/en-US/docs
## async method: Worker.evaluate
- returns: <[Serializable]>
Returns the return value of [`param: pageFunction`]
Returns the return value of [`param: expression`]
If the function passed to the `worker.evaluate` returns a [Promise], then `worker.evaluate` would wait for the promise
to resolve and return its value.
@ -49,12 +49,12 @@ If the function passed to the `worker.evaluate` returns a non-[Serializable] val
### param: Worker.evaluate.arg
- `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`]
Optional argument to pass to [`param: expression`]
## async method: Worker.evaluateHandle
- returns: <[JSHandle]>
Returns the return value of [`param: pageFunction`] as in-page object (JSHandle).
Returns the return value of [`param: expression`] as in-page object (JSHandle).
The only difference between `worker.evaluate` and `worker.evaluateHandle` is that `worker.evaluateHandle` returns
in-page object (JSHandle).
@ -67,7 +67,7 @@ the promise to resolve and return its value.
### param: Worker.evaluateHandle.arg
- `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`]
Optional argument to pass to [`param: expression`]
## method: Worker.url
- returns: <[string]>

37
utils/doclint/documentation.js
View File

@ -118,17 +118,21 @@ class Documentation {
for (const member of clazz.membersArray)
membersMap.set(`${member.kind}: ${clazz.name}.${member.name}`, member);
}
this._patchLinks = nodes => patchLinks(nodes, classesMap, membersMap, linkRenderer);
/**
* @param {Documentation.Class|Documentation.Member|null} classOrMember
* @param {MarkdownNode[]} nodes
*/
this._patchLinks = (classOrMember, nodes) => patchLinks(classOrMember, nodes, classesMap, membersMap, linkRenderer);
for (const clazz of this.classesArray)
clazz.visit(item => this._patchLinks(item.spec));
clazz.visit(item => this._patchLinks(item, item.spec));
}
/**
* @param {MarkdownNode[]} nodes
*/
renderLinksInText(nodes) {
this._patchLinks(nodes);
this._patchLinks(null, nodes);
}
generateSourceCodeComments() {
@ -288,6 +292,8 @@ Documentation.Member = class {
this.index();
/** @type {!Documentation.Class} */
this.clazz = null;
/** @type {Documentation.Member=} */
this.enclosingMethod = undefined;
this.deprecated = false;
if (spec) {
md.visitAll(spec, node => {
@ -301,10 +307,15 @@ Documentation.Member = class {
index() {
this.args = new Map();
if (this.kind === 'method')
this.enclosingMethod = this;
for (const arg of this.argsArray) {
this.args.set(arg.name, arg);
if (arg.name === 'options')
arg.enclosingMethod = this;
if (arg.name === 'options') {
arg.type.properties.sort((p1, p2) => p1.name.localeCompare(p2.name));
arg.type.properties.forEach(p => p.enclosingMethod = this);
}
}
}
@ -588,12 +599,13 @@ function matchingBracket(str, open, close) {
}
/**
* @param {Documentation.Class|Documentation.Member|null} classOrMember
* @param {MarkdownNode[]} spec
* @param {Map<string, Documentation.Class>} classesMap
* @param {Map<string, Documentation.Member>} membersMap
* @param {Renderer} linkRenderer
*/
function patchLinks(spec, classesMap, membersMap, linkRenderer) {
function patchLinks(classOrMember, spec, classesMap, membersMap, linkRenderer) {
if (!spec)
return;
md.visitAll(spec, node => {
@ -606,8 +618,19 @@ function patchLinks(spec, classesMap, membersMap, linkRenderer) {
return linkRenderer({ member }) || match;
});
node.text = node.text.replace(/\[`(param|option): ([^\]]+)`\]/g, (match, p1, p2) => {
if (p1 === 'param')
return linkRenderer({ param: p2 }) || match;
if (p1 === 'param') {
let alias = p2;
if (classOrMember) {
// param/option reference can only be in method or same method parameter comments.
// @ts-ignore
const method = classOrMember.enclosingMethod;
const param = method.argsArray.find(a => a.name === p2);
if (!param)
throw new Error(`Referenced parameter ${match} not found in the parent method ${method.name} `);
alias = param.alias;
}
return linkRenderer({ param: alias }) || match;
}
if (p1 === 'option')
return linkRenderer({ option: p2 }) || match;
});

1
utils/doclint/generateApiJson.js
View File

@ -87,6 +87,7 @@ function sanitize(result) {
delete result.args;
delete result.argsArray;
delete result.clazz;
delete result.enclosingMethod;
delete result.spec;
}