From 21041bc33186c48c2ea3f44d0e87ff5393b9ac98 Mon Sep 17 00:00:00 2001 From: Yury Semikhatsky Date: Thu, 28 Jan 2021 17:51:41 -0800 Subject: [PATCH] docs: support argument overrides (#5200) --- docs/src/api/class-browsercontext.md | 1 - docs/src/api/class-elementhandle.md | 12 ++----- docs/src/api/class-frame.md | 30 +++-------------- docs/src/api/class-jshandle.md | 12 ++----- docs/src/api/class-page.md | 31 +++--------------- docs/src/api/class-worker.md | 12 ++----- docs/src/api/javascript.md | 16 +++++++++ docs/src/api/params.md | 37 +++++++++++++++++---- docs/src/api/python.md | 49 +++++++++------------------- types/types.d.ts | 24 +++++++------- utils/doclint/api_parser.js | 18 ++++++++-- utils/doclint/documentation.js | 13 ++++---- utils/doclint/missingDocs.js | 10 +++--- utils/generate_types/index.js | 22 ++++++------- 14 files changed, 128 insertions(+), 159 deletions(-) create mode 100644 docs/src/api/javascript.md diff --git a/docs/src/api/class-browsercontext.md b/docs/src/api/class-browsercontext.md index 8ca99a755ab14..e599498ea0c52 100644 --- a/docs/src/api/class-browsercontext.md +++ b/docs/src/api/class-browsercontext.md @@ -153,7 +153,6 @@ 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 current working directory. Optional. diff --git a/docs/src/api/class-elementhandle.md b/docs/src/api/class-elementhandle.md index 5d6307f344a9f..c8120a8a3d4fe 100644 --- a/docs/src/api/class-elementhandle.md +++ b/docs/src/api/class-elementhandle.md @@ -114,11 +114,7 @@ assert tweet_handle.eval_on_selector(".retweets", "node => node.innerText") = "1 ### param: ElementHandle.$eval.selector = %%-query-selector-%% -### param: ElementHandle.$eval.pageFunction -* langs: js -- `pageFunction` <[function]\([Element]\)> - -Function to be evaluated in browser context +### param: ElementHandle.$eval.expression = %%-evaluate-expression-%% ### param: ElementHandle.$eval.arg - `arg` <[EvaluationArgument]> @@ -165,11 +161,7 @@ assert feed_handle.eval_on_selector_all(".tweet", "nodes => nodes.map(n => n.inn ### param: ElementHandle.$$eval.selector = %%-query-selector-%% -### param: ElementHandle.$$eval.pageFunction -* langs: js -- `pageFunction` <[function]\([Array]<[Element]>\)> - -Function to be evaluated in browser context +### param: ElementHandle.$$eval.expression = %%-evaluate-expression-%% ### param: ElementHandle.$$eval.arg - `arg` <[EvaluationArgument]> diff --git a/docs/src/api/class-frame.md b/docs/src/api/class-frame.md index 003b21cbb04ea..7546aa97bf733 100644 --- a/docs/src/api/class-frame.md +++ b/docs/src/api/class-frame.md @@ -136,11 +136,7 @@ html = frame.eval_on_selector(".main-container", "(e, suffix) => e.outerHTML + s ### param: Frame.$eval.selector = %%-query-selector-%% -### param: Frame.$eval.pageFunction -* langs: js -- `pageFunction` <[function]\([Element]\)> - -Function to be evaluated in browser context +### param: Frame.$eval.expression = %%-evaluate-expression-%% ### param: Frame.$eval.arg - `arg` <[EvaluationArgument]> @@ -177,11 +173,7 @@ divs_counts = frame.eval_on_selector_all("div", "(divs, min) => divs.length >= m ### param: Frame.$$eval.selector = %%-query-selector-%% -### param: Frame.$$eval.pageFunction -* langs: js -- `pageFunction` <[function]\([Array]<[Element]>\)> - -Function to be evaluated in browser context +### param: Frame.$$eval.expression = %%-evaluate-expression-%% ### param: Frame.$$eval.arg - `arg` <[EvaluationArgument]> @@ -477,11 +469,7 @@ html = frame.evaluate("([body, suffix]) => body.innerHTML + suffix", [body_handl body_handle.dispose() ``` -### param: Frame.evaluate.pageFunction -* langs: js -- `pageFunction` <[function]|[string]> - -Function to be evaluated in browser context +### param: Frame.evaluate.expression = %%-evaluate-expression-%% ### param: Frame.evaluate.arg - `arg` <[EvaluationArgument]> @@ -551,11 +539,7 @@ print(result_handle.json_value()) result_handle.dispose() ``` -### param: Frame.evaluateHandle.pageFunction -* langs: js -- `pageFunction` <[function]|[string]> - -Function to be evaluated in the page context +### param: Frame.evaluateHandle.expression = %%-evaluate-expression-%% ### param: Frame.evaluateHandle.arg - `arg` <[EvaluationArgument]> @@ -1089,11 +1073,7 @@ selector = ".foo" frame.wait_for_function("selector => !!document.querySelector(selector)", selector) ``` -### param: Frame.waitForFunction.pageFunction -* langs: js -- `pageFunction` <[function]|[string]> - -Function to be evaluated in browser context +### param: Frame.waitForFunction.expression = %%-evaluate-expression-%% ### param: Frame.waitForFunction.arg - `arg` <[EvaluationArgument]> diff --git a/docs/src/api/class-jshandle.md b/docs/src/api/class-jshandle.md index c2945c57cfd49..de0ff1c5f7662 100644 --- a/docs/src/api/class-jshandle.md +++ b/docs/src/api/class-jshandle.md @@ -61,11 +61,7 @@ tweet_handle = page.query_selector(".tweet .retweets") assert tweet_handle.evaluate("node => node.innerText") == "10 retweets" ``` -### param: JSHandle.evaluate.pageFunction -* langs: js -- `pageFunction` <[function]> - -Function to be evaluated in browser context +### param: JSHandle.evaluate.expression = %%-evaluate-expression-%% ### param: JSHandle.evaluate.arg - `arg` <[EvaluationArgument]> @@ -87,11 +83,7 @@ for the promise to resolve and return its value. See [`method: Page.evaluateHandle`] for more details. -### param: JSHandle.evaluateHandle.pageFunction -* langs: js -- `pageFunction` <[function]|[string]> - -Function to be evaluated +### param: JSHandle.evaluateHandle.expression = %%-evaluate-expression-%% ### param: JSHandle.evaluateHandle.arg - `arg` <[EvaluationArgument]> diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md index 918baddba90ed..c5125bb817fac 100644 --- a/docs/src/api/class-page.md +++ b/docs/src/api/class-page.md @@ -369,11 +369,7 @@ Shortcut for main frame's [`method: Frame.$eval`]. ### param: Page.$eval.selector = %%-query-selector-%% -### param: Page.$eval.pageFunction -* langs: js -- `pageFunction` <[function]\([Element]\)> - -Function to be evaluated in browser context +### param: Page.$eval.expression = %%-evaluate-expression-%% ### param: Page.$eval.arg - `arg` <[EvaluationArgument]> @@ -407,11 +403,7 @@ div_counts = page.eval_on_selector_all("div", "(divs, min) => divs.length >= min ### param: Page.$$eval.selector = %%-query-selector-%% -### param: Page.$$eval.pageFunction -* langs: js -- `pageFunction` <[function]\([Array]<[Element]>\)> - -Function to be evaluated in browser context +### param: Page.$$eval.expression = %%-evaluate-expression-%% ### param: Page.$$eval.arg - `arg` <[EvaluationArgument]> @@ -459,7 +451,6 @@ 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 current working directory. Optional. @@ -903,11 +894,7 @@ body_handle.dispose() Shortcut for main frame's [`method: Frame.evaluate`]. -### param: Page.evaluate.pageFunction -* langs: js -- `pageFunction` <[function]|[string]> - -Function to be evaluated in the page context +### param: Page.evaluate.expression = %%-evaluate-expression-%% ### param: Page.evaluate.arg - `arg` <[EvaluationArgument]> @@ -977,11 +964,7 @@ print(result_handle.json_value()) result_handle.dispose() ``` -### param: Page.evaluateHandle.pageFunction -* langs: js -- `pageFunction` <[function]|[string]> - -Function to be evaluated in the page context +### param: Page.evaluateHandle.expression = %%-evaluate-expression-%% ### param: Page.evaluateHandle.arg - `arg` <[EvaluationArgument]> @@ -2279,11 +2262,7 @@ page.wait_for_function("selector => !!document.querySelector(selector)", selecto Shortcut for main frame's [`method: Frame.waitForFunction`]. -### param: Page.waitForFunction.pageFunction -* langs: js -- `pageFunction` <[function]|[string]> - -Function to be evaluated in browser context +### param: Page.waitForFunction.expression = %%-evaluate-expression-%% ### param: Page.waitForFunction.arg - `arg` <[EvaluationArgument]> diff --git a/docs/src/api/class-worker.md b/docs/src/api/class-worker.md index eaea475a7406f..8cfd0160d4964 100644 --- a/docs/src/api/class-worker.md +++ b/docs/src/api/class-worker.md @@ -44,11 +44,7 @@ If the function passed to the `worker.evaluate` returns a non-[Serializable] val `undefined`. DevTools Protocol also supports transferring some additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals. -### param: Worker.evaluate.pageFunction -* langs: js -- `pageFunction` <[function]|[string]> - -Function to be evaluated in the worker context +### param: Worker.evaluate.expression = %%-evaluate-expression-%% ### param: Worker.evaluate.arg - `arg` <[EvaluationArgument]> @@ -66,11 +62,7 @@ in-page object (JSHandle). If the function passed to the `worker.evaluateHandle` returns a [Promise], then `worker.evaluateHandle` would wait for the promise to resolve and return its value. -### param: Worker.evaluateHandle.pageFunction -* langs: js -- `pageFunction` <[function]|[string]> - -Function to be evaluated in the page context +### param: Worker.evaluateHandle.expression = %%-evaluate-expression-%% ### param: Worker.evaluateHandle.arg - `arg` <[EvaluationArgument]> diff --git a/docs/src/api/javascript.md b/docs/src/api/javascript.md new file mode 100644 index 0000000000000..fbeb10fca6b8d --- /dev/null +++ b/docs/src/api/javascript.md @@ -0,0 +1,16 @@ +### param: ElementHandle.$eval.expression = %%-js-evalonselector-pagefunction-%% +### param: ElementHandle.$$eval.expression = %%-js-evalonselectorall-pagefunction-%% +### param: Frame.$eval.expression = %%-js-evalonselector-pagefunction-%% +### param: Frame.$$eval.expression = %%-js-evalonselectorall-pagefunction-%% +### param: Frame.evaluate.expression = %%-js-evaluate-pagefunction-%% +### param: Frame.evaluateHandle.expression = %%-js-evaluate-pagefunction-%% +### param: Frame.waitForFunction.expression = %%-js-evaluate-pagefunction-%% +### param: JSHandle.evaluate.expression = %%-js-evaluate-pagefunction-%% +### param: JSHandle.evaluateHandle.expression = %%-js-evaluate-pagefunction-%% +### param: Page.$eval.expression = %%-js-evalonselector-pagefunction-%% +### param: Page.$$eval.expression = %%-js-evalonselectorall-pagefunction-%% +### param: Page.evaluate.expression = %%-js-evaluate-pagefunction-%% +### param: Page.evaluateHandle.expression = %%-js-evaluate-pagefunction-%% +### param: Page.waitForFunction.expression = %%-js-evaluate-pagefunction-%% +### param: Worker.evaluate.expression = %%-js-worker-evaluate-workerfunction-%% +### param: Worker.evaluateHandle.expression = %%-js-worker-evaluate-workerfunction-%% diff --git a/docs/src/api/params.md b/docs/src/api/params.md index b658e027bcc93..99175c3ef390a 100644 --- a/docs/src/api/params.md +++ b/docs/src/api/params.md @@ -154,6 +154,36 @@ Toggles bypassing page's Content-Security-Policy. Sets a consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport. +## evaluate-expression +- `expression` <[string]> + +JavaScript expression to be evaluated in the browser context. If it looks like a function declaration, +it is interpreted as a function. Otherwise, evaluated as an expression. + +## js-evaluate-pagefunction +* langs: js +- `pageFunction` <[function]|[string]> + +Function to be evaluated in the page context + +## js-evalonselector-pagefunction +* langs: js +- `pageFunction` <[function]\([Element]\)> + +Function to be evaluated in the page context + +## js-evalonselectorall-pagefunction +* langs: js +- `pageFunction` <[function]\([Array]<[Element]>\)> + +Function to be evaluated in the page context + +## js-worker-evaluate-workerfunction +* langs: js +- `pageFunction` <[function]|[string]> + +Function to be evaluated in the worker context + ## python-context-option-viewport * langs: python - `viewport` <[null]|[Object]> @@ -394,13 +424,6 @@ Receives the event data and resolves to truthy value when the waiting should res 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`]. -## python-evaluate-expression -* langs: python -- `expression` - -JavaScript expression to be evaluated in the browser context. If it looks like a function declaration, -it is interpreted as a function. Otherwise, evaluated as an expression. - ## python-evaluate-force-expression * langs: python - `force_expr` diff --git a/docs/src/api/python.md b/docs/src/api/python.md index 4dbfe602d8b92..c7a3ec1471ed7 100644 --- a/docs/src/api/python.md +++ b/docs/src/api/python.md @@ -275,36 +275,19 @@ Will throw an error if the socket is closed before the `event` is fired. ### option: WebSocket.waitForEvent2.predicate = %%-python-wait-for-event-predicate-%% ### option: WebSocket.waitForEvent2.timeout = %%-python-wait-for-event-timeout-%% -### param: ElementHandle.$eval.expression = %%-python-evaluate-expression-%% -### param: ElementHandle.$$eval.expression = %%-python-evaluate-expression-%% -### param: Frame.$eval.expression = %%-python-evaluate-expression-%% -### param: Frame.$$eval.expression = %%-python-evaluate-expression-%% -### param: Frame.evaluate.expression = %%-python-evaluate-expression-%% -### param: Frame.evaluateHandle.expression = %%-python-evaluate-expression-%% -### param: Frame.waitForFunction.expression = %%-python-evaluate-expression-%% -### param: JSHandle.evaluate.expression = %%-python-evaluate-expression-%% -### param: JSHandle.evaluateHandle.expression = %%-python-evaluate-expression-%% -### param: Page.$eval.expression = %%-python-evaluate-expression-%% -### param: Page.$$eval.expression = %%-python-evaluate-expression-%% -### param: Page.evaluate.expression = %%-python-evaluate-expression-%% -### param: Page.evaluateHandle.expression = %%-python-evaluate-expression-%% -### param: Page.waitForFunction.expression = %%-python-evaluate-expression-%% -### param: Worker.evaluate.expression = %%-python-evaluate-expression-%% -### param: Worker.evaluateHandle.expression = %%-python-evaluate-expression-%% - -### param: ElementHandle.$eval.expression = %%-python-evaluate-force-expression-%% -### param: ElementHandle.$$eval.expression = %%-python-evaluate-force-expression-%% -### param: Frame.$eval.expression = %%-python-evaluate-force-expression-%% -### param: Frame.$$eval.expression = %%-python-evaluate-force-expression-%% -### param: Frame.evaluate.expression = %%-python-evaluate-force-expression-%% -### param: Frame.evaluateHandle.expression = %%-python-evaluate-force-expression-%% -### param: Frame.waitForFunction.expression = %%-python-evaluate-force-expression-%% -### param: JSHandle.evaluate.expression = %%-python-evaluate-force-expression-%% -### param: JSHandle.evaluateHandle.expression = %%-python-evaluate-force-expression-%% -### param: Page.$eval.expression = %%-python-evaluate-force-expression-%% -### param: Page.$$eval.expression = %%-python-evaluate-force-expression-%% -### param: Page.evaluate.expression = %%-python-evaluate-force-expression-%% -### param: Page.evaluateHandle.expression = %%-python-evaluate-force-expression-%% -### param: Page.waitForFunction.expression = %%-python-evaluate-force-expression-%% -### param: Worker.evaluate.expression = %%-python-evaluate-force-expression-%% -### param: Worker.evaluateHandle.expression = %%-python-evaluate-force-expression-%% +### param: ElementHandle.$eval.foce_expression = %%-python-evaluate-force-expression-%% +### param: ElementHandle.$$eval.foce_expression = %%-python-evaluate-force-expression-%% +### param: Frame.$eval.foce_expression = %%-python-evaluate-force-expression-%% +### param: Frame.$$eval.foce_expression = %%-python-evaluate-force-expression-%% +### param: Frame.evaluate.foce_expression = %%-python-evaluate-force-expression-%% +### param: Frame.evaluateHandle.foce_expression = %%-python-evaluate-force-expression-%% +### param: Frame.waitForFunction.foce_expression = %%-python-evaluate-force-expression-%% +### param: JSHandle.evaluate.foce_expression = %%-python-evaluate-force-expression-%% +### param: JSHandle.evaluateHandle.foce_expression = %%-python-evaluate-force-expression-%% +### param: Page.$eval.foce_expression = %%-python-evaluate-force-expression-%% +### param: Page.$$eval.foce_expression = %%-python-evaluate-force-expression-%% +### param: Page.evaluate.foce_expression = %%-python-evaluate-force-expression-%% +### param: Page.evaluateHandle.foce_expression = %%-python-evaluate-force-expression-%% +### param: Page.waitForFunction.foce_expression = %%-python-evaluate-force-expression-%% +### param: Worker.evaluate.foce_expression = %%-python-evaluate-force-expression-%% +### param: Worker.evaluateHandle.foce_expression = %%-python-evaluate-force-expression-%% diff --git a/types/types.d.ts b/types/types.d.ts index 3f521da8b91d2..0a0ea1f21735d 100644 --- a/types/types.d.ts +++ b/types/types.d.ts @@ -204,7 +204,7 @@ export interface Page { * Shortcut for main frame's * [frame.$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-frame#frameevalselector-pagefunction-arg). * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. - * @param pageFunction Function to be evaluated in browser context + * @param pageFunction Function to be evaluated in the page context * @param arg Optional argument to pass to `pageFunction` */ $eval(selector: K, pageFunction: PageFunctionOn, arg: Arg): Promise; @@ -227,7 +227,7 @@ export interface Page { * ``` * * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. - * @param pageFunction Function to be evaluated in browser context + * @param pageFunction Function to be evaluated in the page context * @param arg Optional argument to pass to `pageFunction` */ $$eval(selector: K, pageFunction: PageFunctionOn, arg: Arg): Promise; @@ -266,7 +266,7 @@ export interface Page { * * Shortcut for main frame's * [frame.waitForFunction(pageFunction[, arg, options])](https://playwright.dev/docs/api/class-frame#framewaitforfunctionpagefunction-arg-options). - * @param pageFunction Function to be evaluated in browser context + * @param pageFunction Function to be evaluated in the page context * @param arg Optional argument to pass to `pageFunction` * @param options */ @@ -3215,7 +3215,7 @@ export interface Frame { * await bodyHandle.dispose(); * ``` * - * @param pageFunction Function to be evaluated in browser context + * @param pageFunction Function to be evaluated in the page context * @param arg Optional argument to pass to `pageFunction` */ evaluate(pageFunction: PageFunction, arg: Arg): Promise; @@ -3300,7 +3300,7 @@ export interface Frame { * ``` * * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. - * @param pageFunction Function to be evaluated in browser context + * @param pageFunction Function to be evaluated in the page context * @param arg Optional argument to pass to `pageFunction` */ $eval(selector: K, pageFunction: PageFunctionOn, arg: Arg): Promise; @@ -3323,7 +3323,7 @@ export interface Frame { * ``` * * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. - * @param pageFunction Function to be evaluated in browser context + * @param pageFunction Function to be evaluated in the page context * @param arg Optional argument to pass to `pageFunction` */ $$eval(selector: K, pageFunction: PageFunctionOn, arg: Arg): Promise; @@ -3358,7 +3358,7 @@ export interface Frame { * await frame.waitForFunction(selector => !!document.querySelector(selector), selector); * ``` * - * @param pageFunction Function to be evaluated in browser context + * @param pageFunction Function to be evaluated in the page context * @param arg Optional argument to pass to `pageFunction` * @param options */ @@ -5120,7 +5120,7 @@ export interface Worker { * * If the function passed to the `worker.evaluateHandle` returns a [Promise], then `worker.evaluateHandle` would wait for * the promise to resolve and return its value. - * @param pageFunction Function to be evaluated in the page context + * @param pageFunction Function to be evaluated in the worker context * @param arg Optional argument to pass to `pageFunction` */ evaluateHandle(pageFunction: PageFunction, arg: Arg): Promise>; @@ -5188,7 +5188,7 @@ export interface JSHandle { * expect(await tweetHandle.evaluate(node => node.innerText)).toBe('10 retweets'); * ``` * - * @param pageFunction Function to be evaluated in browser context + * @param pageFunction Function to be evaluated in the page context * @param arg Optional argument to pass to `pageFunction` */ evaluate(pageFunction: PageFunctionOn, arg: Arg): Promise; @@ -5208,7 +5208,7 @@ export interface JSHandle { * See * [page.evaluateHandle(pageFunction[, arg])](https://playwright.dev/docs/api/class-page#pageevaluatehandlepagefunction-arg) * for more details. - * @param pageFunction Function to be evaluated + * @param pageFunction Function to be evaluated in the page context * @param arg Optional argument to pass to `pageFunction` */ evaluateHandle(pageFunction: PageFunctionOn, arg: Arg): Promise>; @@ -5313,7 +5313,7 @@ export interface ElementHandle extends JSHandle { * ``` * * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. - * @param pageFunction Function to be evaluated in browser context + * @param pageFunction Function to be evaluated in the page context * @param arg Optional argument to pass to `pageFunction` */ $eval(selector: K, pageFunction: PageFunctionOn, arg: Arg): Promise; @@ -5344,7 +5344,7 @@ export interface ElementHandle extends JSHandle { * ``` * * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details. - * @param pageFunction Function to be evaluated in browser context + * @param pageFunction Function to be evaluated in the page context * @param arg Optional argument to pass to `pageFunction` */ $$eval(selector: K, pageFunction: PageFunctionOn, arg: Arg): Promise; diff --git a/utils/doclint/api_parser.js b/utils/doclint/api_parser.js index 682d20300b27b..bcdddc912b1f6 100644 --- a/utils/doclint/api_parser.js +++ b/utils/doclint/api_parser.js @@ -121,8 +121,21 @@ class ApiParser { const method = clazz.membersArray.find(m => m.kind === 'method' && m.name === match[3]); if (!method) throw new Error('Invalid method ' + match[2] + '.' + match[3]); + const name = match[4]; + if (!name) + throw new Error('Invalid member name ' + spec.text); if (match[1] === 'param') { - method.argsArray.push(this.parseProperty(spec)); + const arg = this.parseProperty(spec); + arg.name = name; + const existingArg = method.argsArray.find(m => m.name === arg.name); + if (existingArg) { + for (const lang of arg.langs.only) { + existingArg.langs.overrides = existingArg.langs.overrides || {}; + existingArg.langs.overrides[lang] = arg; + } + } else { + method.argsArray.push(arg); + } } else { let options = method.argsArray.find(o => o.name === 'options'); if (!options) { @@ -302,7 +315,8 @@ function extractLangs(spec) { return { only: only ? only.split(',') : undefined, aliases, - types: {} + types: {}, + overrides: {} }; } return {}; diff --git a/utils/doclint/documentation.js b/utils/doclint/documentation.js index 10c0edd9885ef..851b9ca543565 100644 --- a/utils/doclint/documentation.js +++ b/utils/doclint/documentation.js @@ -35,7 +35,8 @@ const md = require('../markdown'); * @typedef {{ * only?: string[], * aliases?: Object, - * types?: Object, + * types?: Object, + * overrides?: Object, * }} Langs */ @@ -320,13 +321,11 @@ Documentation.Member = class { for (const arg of this.argsArray) { if (arg.langs.only && !arg.langs.only.includes(lang)) continue; - if (arg.langs.aliases && arg.langs.aliases[lang]) - arg.alias = arg.langs.aliases[lang]; - arg.filterForLanguage(lang); - arg.type.filterForLanguage(lang); - if (arg.name === 'options' && !arg.type.properties.length) + const overriddenArg = (arg.langs.overrides && arg.langs.overrides[lang]) || arg; + overriddenArg.filterForLanguage(lang); + if (overriddenArg.name === 'options' && !overriddenArg.type.properties.length) continue; - argsArray.push(arg); + argsArray.push(overriddenArg); } this.argsArray = argsArray; } diff --git a/utils/doclint/missingDocs.js b/utils/doclint/missingDocs.js index 42d4393f8e5b9..291c24d4fd1b7 100644 --- a/utils/doclint/missingDocs.js +++ b/utils/doclint/missingDocs.js @@ -32,7 +32,7 @@ module.exports = function lint(documentation, jsSources, apiFileName) { continue; } for (const [methodName, params] of methods) { - const member = docClass.members.get(methodName); + const member = docClass.membersArray.find(m => m.alias === methodName && m.kind !== 'event'); if (!member) { errors.push(`Missing documentation for "${className}.${methodName}"`); continue; @@ -53,15 +53,15 @@ module.exports = function lint(documentation, jsSources, apiFileName) { for (const member of cls.membersArray) { if (member.kind === 'event') continue; - const params = methods.get(member.name); + const params = methods.get(member.alias); if (!params) { - errors.push(`Documented "${cls.name}.${member.name}" not found is sources`); + errors.push(`Documented "${cls.name}.${member.alias}" not found is sources`); continue; } const memberParams = paramsForMember(member); for (const paramName of memberParams) { if (!params.has(paramName) && paramName !== 'options') - errors.push(`Documented "${cls.name}.${member.name}.${paramName}" not found is sources`); + errors.push(`Documented "${cls.name}.${member.alias}.${paramName}" not found is sources`); } } } @@ -74,7 +74,7 @@ module.exports = function lint(documentation, jsSources, apiFileName) { function paramsForMember(member) { if (member.kind !== 'method') return new Set(); - return new Set(member.argsArray.map(a => a.name)); + return new Set(member.argsArray.map(a => a.alias)); } /** diff --git a/utils/generate_types/index.js b/utils/generate_types/index.js index 0b07b0b7d29a1..9a202c87f64c5 100644 --- a/utils/generate_types/index.js +++ b/utils/generate_types/index.js @@ -52,11 +52,11 @@ let hadChanges = false; if (clazz) return `[${clazz.name}]`; if (member.kind === 'method') - return createMemberLink(member.clazz, `${member.clazz.varName}.${member.name}(${renderJSSignature(member.argsArray)})`); + return createMemberLink(member.clazz, `${member.clazz.varName}.${member.alias}(${renderJSSignature(member.argsArray)})`); if (member.kind === 'event') - return createMemberLink(member.clazz, `${member.clazz.varName}.on('${member.name}')`); + return createMemberLink(member.clazz, `${member.clazz.varName}.on('${member.alias}')`); if (member.kind === 'property') - return createMemberLink(member.clazz, `${member.clazz.varName}.${member.name}`); + return createMemberLink(member.clazz, `${member.clazz.varName}.${member.alias}`); throw new Error('Unknown member kind ' + member.kind); }); documentation.generateSourceCodeComments(); @@ -137,7 +137,7 @@ function objectDefinitionsToString(overriddes) { } function nameForProperty(member) { - return (member.required || member.name.startsWith('...')) ? member.name : member.name + '?'; + return (member.required || member.alias.startsWith('...')) ? member.alias : member.alias + '?'; } /** @@ -216,25 +216,25 @@ function classBody(classDesc) { parts.push(members.map(member => { if (member.kind === 'event') return ''; - if (member.name === 'waitForEvent') { + if (member.alias === 'waitForEvent') { const parts = []; for (const {eventName, params, comment, type} of eventDescriptions) { if (comment) parts.push(writeComment(comment, ' ')); - parts.push(` ${member.name}(event: '${eventName}', optionsOrPredicate?: { predicate?: (${params}) => boolean, timeout?: number } | ((${params}) => boolean)): Promise<${type}>;\n`); + parts.push(` ${member.alias}(event: '${eventName}', optionsOrPredicate?: { predicate?: (${params}) => boolean, timeout?: number } | ((${params}) => boolean)): Promise<${type}>;\n`); } return parts.join('\n'); } const jsdoc = memberJSDOC(member, ' '); const args = argsFromMember(member, ' ', classDesc.name); - let type = stringifyComplexType(member.type, ' ', classDesc.name, member.name); + let type = stringifyComplexType(member.type, ' ', classDesc.name, member.alias); if (member.async) type = `Promise<${type}>`; // do this late, because we still want object definitions for overridden types - if (!hasOwnMethod(classDesc, member.name)) + if (!hasOwnMethod(classDesc, member.alias)) return ''; - return `${jsdoc}${member.name}${args}: ${type};` + return `${jsdoc}${member.alias}${args}: ${type};` }).filter(x => x).join('\n\n')); return parts.join('\n'); } @@ -375,7 +375,7 @@ function memberJSDOC(member, indent) { lines.push(...member.comment.split('\n')); if (member.deprecated) lines.push('@deprecated'); - lines.push(...member.argsArray.map(arg => `@param ${arg.name.replace(/\./g, '')} ${arg.comment.replace('\n', ' ')}`)); + lines.push(...member.argsArray.map(arg => `@param ${arg.alias.replace(/\./g, '')} ${arg.comment.replace('\n', ' ')}`)); if (!lines.length) return indent; return writeComment(lines.join('\n'), indent) + '\n' + indent; @@ -399,7 +399,7 @@ function renderJSSignature(args) { const tokens = []; let hasOptional = false; for (const arg of args) { - const name = arg.name; + const name = arg.alias; const optional = !arg.required; if (tokens.length) { if (optional && !hasOptional)