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

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

View File

@ -247,13 +247,13 @@ Optional event-specific initialization properties.
- alias-js: $eval - alias-js: $eval
- returns: <[Serializable]> - 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 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. 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. value.
Examples: Examples:
@ -283,7 +283,7 @@ assert tweet_handle.eval_on_selector(".retweets", "node => node.innerText") = "1
### param: ElementHandle.evalOnSelector.arg ### param: ElementHandle.evalOnSelector.arg
- `arg` <[EvaluationArgument]> - `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`] Optional argument to pass to [`param: expression`]
## async method: ElementHandle.evalOnSelectorAll ## async method: ElementHandle.evalOnSelectorAll
* langs: * langs:
@ -291,13 +291,13 @@ Optional argument to pass to [`param: pageFunction`]
- alias-js: $$eval - alias-js: $$eval
- returns: <[Serializable]> - 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 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. [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. value.
Examples: Examples:
@ -331,7 +331,7 @@ assert feed_handle.eval_on_selector_all(".tweet", "nodes => nodes.map(n => n.inn
### param: ElementHandle.evalOnSelectorAll.arg ### param: ElementHandle.evalOnSelectorAll.arg
- `arg` <[EvaluationArgument]> - `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`] Optional argument to pass to [`param: expression`]
## async method: ElementHandle.fill ## async method: ElementHandle.fill

View File

@ -300,13 +300,13 @@ Optional event-specific initialization properties.
- alias-js: $eval - alias-js: $eval
- returns: <[Serializable]> - 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 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. 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. value.
Examples: Examples:
@ -336,7 +336,7 @@ html = frame.eval_on_selector(".main-container", "(e, suffix) => e.outerHTML + s
### param: Frame.evalOnSelector.arg ### param: Frame.evalOnSelector.arg
- `arg` <[EvaluationArgument]> - `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`] Optional argument to pass to [`param: expression`]
## async method: Frame.evalOnSelectorAll ## async method: Frame.evalOnSelectorAll
* langs: * langs:
@ -344,13 +344,13 @@ Optional argument to pass to [`param: pageFunction`]
- alias-js: $$eval - alias-js: $$eval
- returns: <[Serializable]> - 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 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. 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. value.
Examples: Examples:
@ -374,12 +374,12 @@ divs_counts = frame.eval_on_selector_all("div", "(divs, min) => divs.length >= m
### param: Frame.evalOnSelectorAll.arg ### param: Frame.evalOnSelectorAll.arg
- `arg` <[EvaluationArgument]> - `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`] Optional argument to pass to [`param: expression`]
## async method: Frame.evaluate ## async method: Frame.evaluate
- returns: <[Serializable]> - 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 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. resolve and return its value.
@ -450,12 +450,12 @@ body_handle.dispose()
### param: Frame.evaluate.arg ### param: Frame.evaluate.arg
- `arg` <[EvaluationArgument]> - `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`] Optional argument to pass to [`param: expression`]
## async method: Frame.evaluateHandle ## async method: Frame.evaluateHandle
- returns: <[JSHandle]> - 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 The only difference between [`method: Frame.evaluate`] and [`method: Frame.evaluateHandle`] is that
[method: Frame.evaluateHandle`] returns in-page object (JSHandle). [method: Frame.evaluateHandle`] returns in-page object (JSHandle).
@ -520,7 +520,7 @@ result_handle.dispose()
### param: Frame.evaluateHandle.arg ### param: Frame.evaluateHandle.arg
- `arg` <[EvaluationArgument]> - `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`] Optional argument to pass to [`param: expression`]
## async method: Frame.fill ## async method: Frame.fill
@ -1010,7 +1010,7 @@ Returns frame's url.
## async method: Frame.waitForFunction ## async method: Frame.waitForFunction
- returns: <[JSHandle]> - 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: 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 ### param: Frame.waitForFunction.arg
- `arg` <[EvaluationArgument]> - `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`] Optional argument to pass to [`param: expression`]
### option: Frame.waitForFunction.polling ### option: Frame.waitForFunction.polling
- `polling` <[float]|"raf"> - `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 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`. would be executed. Defaults to `raf`.

View File

@ -37,11 +37,11 @@ The `jsHandle.dispose` method stops referencing the element handle.
## async method: JSHandle.evaluate ## async method: JSHandle.evaluate
- returns: <[Serializable]> - 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. its value.
Examples: Examples:
@ -66,14 +66,14 @@ assert tweet_handle.evaluate("node => node.innerText") == "10 retweets"
### param: JSHandle.evaluate.arg ### param: JSHandle.evaluate.arg
- `arg` <[EvaluationArgument]> - `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`] Optional argument to pass to [`param: expression`]
## async method: JSHandle.evaluateHandle ## async method: JSHandle.evaluateHandle
- returns: <[JSHandle]> - 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 The only difference between `jsHandle.evaluate` and `jsHandle.evaluateHandle` is that `jsHandle.evaluateHandle` returns
in-page object (JSHandle). in-page object (JSHandle).
@ -88,7 +88,7 @@ See [`method: Page.evaluateHandle`] for more details.
### param: JSHandle.evaluateHandle.arg ### param: JSHandle.evaluateHandle.arg
- `arg` <[EvaluationArgument]> - `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`] Optional argument to pass to [`param: expression`]
## async method: JSHandle.getProperties ## async method: JSHandle.getProperties
- returns: <[Map]<[string], [JSHandle]>> - returns: <[Map]<[string], [JSHandle]>>

View File

@ -727,10 +727,10 @@ Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`
- returns: <[Serializable]> - returns: <[Serializable]>
The method finds an element matching the specified selector within the page and passes it as a first argument to 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: expression`]. If no elements match the selector, the method throws an error. Returns the value of
[`param: pageFunction`]. [`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. return its value.
Examples: Examples:
@ -762,7 +762,7 @@ Shortcut for main frame's [`method: Frame.evalOnSelector`].
### param: Page.evalOnSelector.arg ### param: Page.evalOnSelector.arg
- `arg` <[EvaluationArgument]> - `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`] Optional argument to pass to [`param: expression`]
## async method: Page.evalOnSelectorAll ## async method: Page.evalOnSelectorAll
* langs: * langs:
@ -771,9 +771,9 @@ Optional argument to pass to [`param: pageFunction`]
- returns: <[Serializable]> - returns: <[Serializable]>
The method finds all elements matching the specified selector within the page and passes an array of matched elements as 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. return its value.
Examples: Examples:
@ -797,12 +797,12 @@ div_counts = page.eval_on_selector_all("div", "(divs, min) => divs.length >= min
### param: Page.evalOnSelectorAll.arg ### param: Page.evalOnSelectorAll.arg
- `arg` <[EvaluationArgument]> - `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`] Optional argument to pass to [`param: expression`]
## async method: Page.evaluate ## async method: Page.evaluate
- returns: <[Serializable]> - 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 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. 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 [`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. that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals.
Passing argument to [`param: pageFunction`]: Passing argument to [`param: expression`]:
```js ```js
const result = await page.evaluate(([x, y]) => { const result = await page.evaluate(([x, y]) => {
@ -877,12 +877,12 @@ Shortcut for main frame's [`method: Frame.evaluate`].
### param: Page.evaluate.arg ### param: Page.evaluate.arg
- `arg` <[EvaluationArgument]> - `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`] Optional argument to pass to [`param: expression`]
## async method: Page.evaluateHandle ## async method: Page.evaluateHandle
- returns: <[JSHandle]> - 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 The only difference between [`method: Page.evaluate`] and [`method: Page.evaluateHandle`] is that [`method: Page.evaluateHandle`] returns in-page
object (JSHandle). object (JSHandle).
@ -947,7 +947,7 @@ result_handle.dispose()
### param: Page.evaluateHandle.arg ### param: Page.evaluateHandle.arg
- `arg` <[EvaluationArgument]> - `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`] Optional argument to pass to [`param: expression`]
## async method: Page.exposeBinding ## async method: Page.exposeBinding
@ -2197,7 +2197,7 @@ Either a predicate that receives an event or an options object. Optional.
## async method: Page.waitForFunction ## async method: Page.waitForFunction
- returns: <[JSHandle]> - 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: 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 ### param: Page.waitForFunction.arg
- `arg` <[EvaluationArgument]> - `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`] Optional argument to pass to [`param: expression`]
### option: Page.waitForFunction.polling ### option: Page.waitForFunction.polling
- `polling` <[float]|"raf"> - `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 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`. would be executed. Defaults to `raf`.

View File

@ -35,7 +35,7 @@ Emitted when this dedicated [WebWorker](https://developer.mozilla.org/en-US/docs
## async method: Worker.evaluate ## async method: Worker.evaluate
- returns: <[Serializable]> - 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 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. 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 ### param: Worker.evaluate.arg
- `arg` <[EvaluationArgument]> - `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`] Optional argument to pass to [`param: expression`]
## async method: Worker.evaluateHandle ## async method: Worker.evaluateHandle
- returns: <[JSHandle]> - 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 The only difference between `worker.evaluate` and `worker.evaluateHandle` is that `worker.evaluateHandle` returns
in-page object (JSHandle). in-page object (JSHandle).
@ -67,7 +67,7 @@ the promise to resolve and return its value.
### param: Worker.evaluateHandle.arg ### param: Worker.evaluateHandle.arg
- `arg` <[EvaluationArgument]> - `arg` <[EvaluationArgument]>
Optional argument to pass to [`param: pageFunction`] Optional argument to pass to [`param: expression`]
## method: Worker.url ## method: Worker.url
- returns: <[string]> - returns: <[string]>

View File

@ -118,17 +118,21 @@ class Documentation {
for (const member of clazz.membersArray) for (const member of clazz.membersArray)
membersMap.set(`${member.kind}: ${clazz.name}.${member.name}`, member); 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) for (const clazz of this.classesArray)
clazz.visit(item => this._patchLinks(item.spec)); clazz.visit(item => this._patchLinks(item, item.spec));
} }
/** /**
* @param {MarkdownNode[]} nodes * @param {MarkdownNode[]} nodes
*/ */
renderLinksInText(nodes) { renderLinksInText(nodes) {
this._patchLinks(nodes); this._patchLinks(null, nodes);
} }
generateSourceCodeComments() { generateSourceCodeComments() {
@ -288,6 +292,8 @@ Documentation.Member = class {
this.index(); this.index();
/** @type {!Documentation.Class} */ /** @type {!Documentation.Class} */
this.clazz = null; this.clazz = null;
/** @type {Documentation.Member=} */
this.enclosingMethod = undefined;
this.deprecated = false; this.deprecated = false;
if (spec) { if (spec) {
md.visitAll(spec, node => { md.visitAll(spec, node => {
@ -301,10 +307,15 @@ Documentation.Member = class {
index() { index() {
this.args = new Map(); this.args = new Map();
if (this.kind === 'method')
this.enclosingMethod = this;
for (const arg of this.argsArray) { for (const arg of this.argsArray) {
this.args.set(arg.name, arg); 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.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 {MarkdownNode[]} spec
* @param {Map<string, Documentation.Class>} classesMap * @param {Map<string, Documentation.Class>} classesMap
* @param {Map<string, Documentation.Member>} membersMap * @param {Map<string, Documentation.Member>} membersMap
* @param {Renderer} linkRenderer * @param {Renderer} linkRenderer
*/ */
function patchLinks(spec, classesMap, membersMap, linkRenderer) { function patchLinks(classOrMember, spec, classesMap, membersMap, linkRenderer) {
if (!spec) if (!spec)
return; return;
md.visitAll(spec, node => { md.visitAll(spec, node => {
@ -606,8 +618,19 @@ function patchLinks(spec, classesMap, membersMap, linkRenderer) {
return linkRenderer({ member }) || match; return linkRenderer({ member }) || match;
}); });
node.text = node.text.replace(/\[`(param|option): ([^\]]+)`\]/g, (match, p1, p2) => { node.text = node.text.replace(/\[`(param|option): ([^\]]+)`\]/g, (match, p1, p2) => {
if (p1 === 'param') if (p1 === 'param') {
return linkRenderer({ param: p2 }) || match; 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') if (p1 === 'option')
return linkRenderer({ option: p2 }) || match; return linkRenderer({ option: p2 }) || match;
}); });

View File

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