diff --git a/docs-src/api-body.md b/docs-src/api-body.md index 6acf3d4be1..c66f4fd4c3 100644 --- a/docs-src/api-body.md +++ b/docs-src/api-body.md @@ -1,8 +1,8 @@ ### class: Browser * extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) -A Browser is created when Playwright connects to a browser instance, either through -[browserType.launch()]() or [browserType.connect()](). +A Browser is created when Playwright connects to a browser instance, either through [browserType.launch()]() or +[browserType.connect()](). An example of using a [Browser] to create a [Page]: @@ -18,31 +18,30 @@ const { firefox } = require('playwright'); // Or 'chromium' or 'webkit'. ``` See [ChromiumBrowser], [FirefoxBrowser] and [WebKitBrowser] for browser-specific features. Note that -[browserType.connect()]() and -[browserType.launch()]() always return a specific browser instance, based on the -browser being connected to or launched. +[browserType.connect()]() and [browserType.launch()]() always return a specific browser instance, based on the browser +being connected to or launched. -#### event: 'disconnected' +#### event Browser.disconnected Emitted when Browser gets disconnected from the browser application. This might happen because of one of the following: * Browser application is closed or crashed. * The [browser.close()]() method was called. -#### browser.close +#### method Browser.close - returns: <[Promise]> -In case this browser is obtained using [browserType.launch()](), closes the browser and all of -its pages (if any were opened). +In case this browser is obtained using [browserType.launch()](), closes the browser and all of its pages (if any were +opened). -In case this browser is obtained using [browserType.connect()](), clears all created contexts -belonging to this browser and disconnects from the browser server. +In case this browser is obtained using [browserType.connect()](), clears all created contexts belonging to this browser +and disconnects from the browser server. The [Browser] object itself is considered to be disposed and cannot be used anymore. -#### browser.contexts +#### method Browser.contexts - returns: <[Array]<[BrowserContext]>> Returns an array of all open browser contexts. In a newly created browser, this will return zero browser contexts. @@ -55,12 +54,12 @@ const context = await browser.newContext(); console.log(browser.contexts().length); // prints `1` ``` -#### browser.isConnected +#### method Browser.isConnected - returns: <[boolean]> Indicates that the browser is connected. -#### browser.newContext +#### method Browser.newContext - `options` <[Object]> - %%-shared-context-params-%%-as-is - %%-context-option-proxy-%% @@ -80,7 +79,7 @@ Creates a new browser context. It won't share cookies/cache with other browser c })(); ``` -#### browser.newPage +#### method Browser.newPage - `options` <[Object]> - %%-shared-context-params-%%-as-is - %%-context-option-proxy-%% @@ -90,10 +89,10 @@ Creates a new browser context. It won't share cookies/cache with other browser c Creates a new page in a new browser context. Closing this page will close the context as well. This is a convenience API that should only be used for the single-page scenarios and short snippets. Production code and -testing frameworks should explicitly create [browser.newContext()]() followed by the -[browserContext.newPage()]() to control their exact life times. +testing frameworks should explicitly create [browser.newContext()]() followed by the [browserContext.newPage()]() to +control their exact life times. -#### browser.version +#### method Browser.version - returns: <[string]> Returns the browser version. @@ -122,19 +121,18 @@ await context.close(); -#### event: 'close' +#### event BrowserContext.close Emitted when Browser context gets closed. This might happen because of one of the following: * Browser context is closed. * Browser application is closed or crashed. * The [browser.close()]() method was called. -#### event: 'page' +#### event BrowserContext.page - <[Page]> The event is emitted when a new Page is created in the BrowserContext. The page may still be loading. The event will -also fire for popup pages. See also [page.on('popup')]() to receive events about popups relevant to a -specific page. +also fire for popup pages. See also [page.on('popup')]() to receive events about popups relevant to a specific page. The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a popup with `window.open('http://example.com')`, this event will fire when the network request to "http://example.com" is @@ -148,10 +146,10 @@ const [page] = await Promise.all([ console.log(await page.evaluate('location.href')); ``` -> **NOTE** Use [page.waitForLoadState()]() to wait until the page -gets to a particular state (you should not need it in most cases). +> **NOTE** Use [page.waitForLoadState()]() to wait until the page gets to a particular state (you should not need it in +most cases). -#### browserContext.addCookies +#### method BrowserContext.addCookies - `cookies` <[Array]<[Object]>> - `name` <[string]> **required** - `value` <[string]> **required** @@ -168,7 +166,7 @@ gets to a particular state (you should not need it in most cases). await browserContext.addCookies([cookieObject1, cookieObject2]); ``` -#### browserContext.addInitScript +#### method BrowserContext.addInitScript - `script` <[function]|[string]|[Object]> Script to be evaluated in all pages in the browser context. - `path` <[string]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). - `content` <[string]> Raw script content. @@ -196,18 +194,18 @@ await browserContext.addInitScript({ }); ``` -> **NOTE** The order of evaluation of multiple scripts installed via [browserContext.addInitScript()]() and [page.addInitScript()]() is -not defined. +> **NOTE** The order of evaluation of multiple scripts installed via [browserContext.addInitScript()]() and +[page.addInitScript()]() is not defined. -#### browserContext.browser +#### method BrowserContext.browser - returns: <[null]|[Browser]> Returns the browser instance of the context. If it was launched as a persistent context null gets returned. -#### browserContext.clearCookies +#### method BrowserContext.clearCookies - returns: <[Promise]> Clears context cookies. -#### browserContext.clearPermissions +#### method BrowserContext.clearPermissions - returns: <[Promise]> Clears all permission overrides for the browser context. @@ -219,14 +217,14 @@ await context.grantPermissions(['clipboard-read']); context.clearPermissions(); ``` -#### browserContext.close +#### method BrowserContext.close - returns: <[Promise]> Closes the browser context. All the pages that belong to the browser context will be closed. > **NOTE** the default browser context cannot be closed. -#### browserContext.cookies +#### method BrowserContext.cookies - `urls` <[string]|[Array]<[string]>> Optional list of URLs. - returns: <[Promise]<[Array]<[Object]>>> - `name` <[string]> @@ -241,7 +239,7 @@ Closes the browser context. All the pages that belong to the browser context wil If no URLs are specified, this method returns all cookies. If URLs are specified, only cookies that affect those URLs are returned. -#### browserContext.exposeBinding +#### method BrowserContext.exposeBinding - `name` <[string]> Name of the function on the window object. - `playwrightBinding` <[function]> Callback function that will be called in the Playwright's context. - `options` <[Object]> @@ -255,8 +253,7 @@ of `playwrightBinding`. If the `playwrightBinding` returns a [Promise], it will The first argument of the `playwrightBinding` function contains information about the caller: `{ browserContext: BrowserContext, page: Page, frame: Frame }`. -See [page.exposeBinding()]() for page-only -version. +See [page.exposeBinding()]() for page-only version. An example of exposing page URL to all frames in all pages in the context: @@ -296,7 +293,7 @@ await page.setContent(` `); ``` -#### browserContext.exposeFunction +#### method BrowserContext.exposeFunction - `name` <[string]> Name of the function on the window object. - `playwrightFunction` <[function]> Callback function that will be called in the Playwright's context. - returns: <[Promise]> @@ -333,7 +330,7 @@ const crypto = require('crypto'); })(); ``` -#### browserContext.grantPermissions +#### method BrowserContext.grantPermissions - `permissions` <[Array]<[string]>> A permission or an array of permissions to grant. Permissions can be one of the following values: - `'geolocation'` - `'midi'` @@ -358,15 +355,15 @@ const crypto = require('crypto'); Grants specified permissions to the browser context. Only grants corresponding permissions to the given origin if specified. -#### browserContext.newPage +#### method BrowserContext.newPage - returns: <[Promise]<[Page]>> Creates a new page in the browser context. -#### browserContext.pages +#### method BrowserContext.pages - returns: <[Array]<[Page]>> All open pages in the context. Non visible pages, such as `"background_page"`, will not be listed here. You can find them using [chromiumBrowserContext.backgroundPages()](). -#### browserContext.route +#### method BrowserContext.route - `url` <[string]|[RegExp]|[function]\([URL]\):[boolean]> A glob pattern, regex pattern or predicate receiving [URL] to match while routing. - `handler` <[function]\([Route], [Request]\)> handler function to route the request. - returns: <[Promise]> @@ -394,12 +391,12 @@ await page.goto('https://example.com'); await browser.close(); ``` -Page routes (set up with [page.route()]()) take precedence over browser context routes -when request matches both handlers. +Page routes (set up with [page.route()]()) take precedence over browser context routes when request matches both +handlers. > **NOTE** Enabling routing disables http cache. -#### browserContext.setDefaultNavigationTimeout +#### method BrowserContext.setDefaultNavigationTimeout - `timeout` <[number]> Maximum navigation time in milliseconds This setting will change the default maximum navigation time for the following methods and related shortcuts: @@ -410,31 +407,28 @@ This setting will change the default maximum navigation time for the following m * [page.setContent()]() * [page.waitForNavigation()]() -> **NOTE** [page.setDefaultNavigationTimeout()]() and -[page.setDefaultTimeout()]() take priority over +> **NOTE** [page.setDefaultNavigationTimeout()]() and [page.setDefaultTimeout()]() take priority over [browserContext.setDefaultNavigationTimeout()](). -#### browserContext.setDefaultTimeout +#### method BrowserContext.setDefaultTimeout - `timeout` <[number]> Maximum time in milliseconds This setting will change the default maximum time for all the methods accepting `timeout` option. -> **NOTE** [page.setDefaultNavigationTimeout()](), -[page.setDefaultTimeout()]() and -[browserContext.setDefaultNavigationTimeout()]() take priority over -[browserContext.setDefaultTimeout()](). +> **NOTE** [page.setDefaultNavigationTimeout()](), [page.setDefaultTimeout()]() and +[browserContext.setDefaultNavigationTimeout()]() take priority over [browserContext.setDefaultTimeout()](). -#### browserContext.setExtraHTTPHeaders +#### method BrowserContext.setExtraHTTPHeaders - `headers` <[Object]<[string], [string]>> An object containing additional HTTP headers to be sent with every request. All header values must be strings. - returns: <[Promise]> The extra HTTP headers will be sent with every request initiated by any page in the context. These headers are merged -with page-specific extra HTTP headers set with [page.setExtraHTTPHeaders()](). If page -overrides a particular header, page-specific header value will be used instead of the browser context header value. +with page-specific extra HTTP headers set with [page.setExtraHTTPHeaders()](). If page overrides a particular header, +page-specific header value will be used instead of the browser context header value. > **NOTE** `browserContext.setExtraHTTPHeaders` does not guarantee the order of headers in the outgoing requests. -#### browserContext.setGeolocation +#### method BrowserContext.setGeolocation - `geolocation` <[null]|[Object]> - `latitude` <[number]> Latitude between -90 and 90. **required** - `longitude` <[number]> Longitude between -180 and 180. **required** @@ -447,10 +441,10 @@ Sets the context's geolocation. Passing `null` or `undefined` emulates position await browserContext.setGeolocation({latitude: 59.95, longitude: 30.31667}); ``` -> **NOTE** Consider using [browserContext.grantPermissions()]() to grant -permissions for the browser context pages to read its geolocation. +> **NOTE** Consider using [browserContext.grantPermissions()]() to grant permissions for the browser context pages to +read its geolocation. -#### browserContext.setHTTPCredentials +#### method BrowserContext.setHTTPCredentials - `httpCredentials` <[null]|[Object]> - `username` <[string]> **required** - `password` <[string]> **required** @@ -462,11 +456,11 @@ Provide credentials for [HTTP authentication](https://developer.mozilla.org/en-U `null` to disable authentication will be unreliable. To remove or replace credentials, create a new browser context instead. -#### browserContext.setOffline +#### method BrowserContext.setOffline - `offline` <[boolean]> Whether to emulate network being offline for the browser context. - returns: <[Promise]> -#### browserContext.storageState +#### method BrowserContext.storageState - returns: <[Promise]<[Object]>> - `cookies` <[Array]<[Object]>> - `name` <[string]> @@ -485,15 +479,15 @@ instead. Returns storage state for this browser context, contains current cookies and local storage snapshot. -#### browserContext.unroute +#### method BrowserContext.unroute - `url` <[string]|[RegExp]|[function]\([URL]\):[boolean]> A glob pattern, regex pattern or predicate receiving [URL] used to register a routing with [browserContext.route()](). - `handler` <[function]\([Route], [Request]\)> Optional handler function used to register a routing with [browserContext.route()](). - returns: <[Promise]> -Removes a route created with [browserContext.route()](). When `handler` is -not specified, removes all routes for the `url`. +Removes a route created with [browserContext.route()](). When `handler` is not specified, removes all routes for the +`url`. -#### browserContext.waitForEvent +#### method BrowserContext.waitForEvent - `event` <[string]> Event name, same one would pass into `browserContext.on(event)`. - `optionsOrPredicate` <[Function]|[Object]> Either a predicate that receives an event or an options object. Optional. - `predicate` <[Function]> receives the event data and resolves to truthy value when the waiting should resolve. @@ -554,11 +548,11 @@ page.removeListener('request', logRequest); -#### event: 'close' +#### event Page.close Emitted when the page closes. -#### event: 'console' +#### event Page.console - <[ConsoleMessage]> Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`. Also @@ -576,7 +570,7 @@ page.on('console', msg => { page.evaluate(() => console.log('hello', 5, {foo: 'bar'})); ``` -#### event: 'crash' +#### event Page.crash Emitted when the page crashes. Browser pages might crash if they try to allocate too much memory. When the page crashes, ongoing and subsequent operations will throw. @@ -607,18 +601,18 @@ await new Promise((resolve, reject) => { }); ``` -#### event: 'dialog' +#### event Page.dialog - <[Dialog]> Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Playwright can respond to the dialog via [dialog.accept()]() or [dialog.dismiss()]() methods. -#### event: 'domcontentloaded' +#### event Page.domcontentloaded Emitted when the JavaScript [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) event is dispatched. -#### event: 'download' +#### event Page.download - <[Download]> Emitted when attachment download started. User can access basic file operations on downloaded content via the passed @@ -628,12 +622,11 @@ Emitted when attachment download started. User can access basic file operations downloaded content. If `acceptDownloads` is not set or set to `false`, download events are emitted, but the actual download is not performed and user has no access to the downloaded files. -#### event: 'filechooser' +#### event Page.filechooser - <[FileChooser]> Emitted when a file chooser is supposed to appear, such as after clicking the ``. Playwright can -respond to it via setting the input files using [fileChooser.setFiles()]() that can be -uploaded after that. +respond to it via setting the input files using [fileChooser.setFiles()]() that can be uploaded after that. ```js page.on('filechooser', async (fileChooser) => { @@ -641,35 +634,35 @@ page.on('filechooser', async (fileChooser) => { }); ``` -#### event: 'frameattached' +#### event Page.frameattached - <[Frame]> Emitted when a frame is attached. -#### event: 'framedetached' +#### event Page.framedetached - <[Frame]> Emitted when a frame is detached. -#### event: 'framenavigated' +#### event Page.framenavigated - <[Frame]> Emitted when a frame is navigated to a new url. -#### event: 'load' +#### event Page.load Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched. -#### event: 'pageerror' +#### event Page.pageerror - <[Error]> The exception message Emitted when an uncaught exception happens within the page. -#### event: 'popup' +#### event Page.popup - <[Page]> Page corresponding to "popup" window -Emitted when the page opens a new tab or window. This event is emitted in addition to the -[browserContext.on('page')](), but only for popups relevant to this page. +Emitted when the page opens a new tab or window. This event is emitted in addition to the [browserContext.on('page')](), +but only for popups relevant to this page. The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a popup with `window.open('http://example.com')`, this event will fire when the network request to "http://example.com" is @@ -683,48 +676,47 @@ const [popup] = await Promise.all([ console.log(await popup.evaluate('location.href')); ``` -> **NOTE** Use [page.waitForLoadState()]() to wait until the page -gets to a particular state (you should not need it in most cases). +> **NOTE** Use [page.waitForLoadState()]() to wait until the page gets to a particular state (you should not need it in +most cases). -#### event: 'request' +#### event Page.request - <[Request]> Emitted when a page issues a request. The [request] object is read-only. In order to intercept and mutate requests, see [page.route()]() or [browserContext.route()](). -#### event: 'requestfailed' +#### event Page.requestfailed - <[Request]> Emitted when a request fails, for example by timing out. > **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request -will complete with [page.on('requestfinished')]() event and not with -[page.on('requestfailed')](). +will complete with [page.on('requestfinished')]() event and not with [page.on('requestfailed')](). -#### event: 'requestfinished' +#### event Page.requestfinished - <[Request]> Emitted when a request finishes successfully after downloading the response body. For a successful response, the sequence of events is `request`, `response` and `requestfinished`. -#### event: 'response' +#### event Page.response - <[Response]> Emitted when [response] status and headers are received for a request. For a successful response, the sequence of events is `request`, `response` and `requestfinished`. -#### event: 'websocket' +#### event Page.websocket - <[WebSocket]> websocket Emitted when <[WebSocket]> request is sent. -#### event: 'worker' +#### event Page.worker - <[Worker]> Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is spawned by the page. -#### page.$ +#### method Page.$ - %%-query-selector-%% - returns: <[Promise]<[null]|[ElementHandle]>> @@ -733,7 +725,7 @@ return value resolves to `null`. Shortcut for main frame's [frame.$()](). -#### page.$$ +#### method Page.$$ - %%-query-selector-%% - returns: <[Promise]<[Array]<[ElementHandle]>>> @@ -742,7 +734,7 @@ return value resolves to `[]`. Shortcut for main frame's [frame.$$()](). -#### page.$eval +#### method Page.$eval - %%-query-selector-%% - `pageFunction` <[function]\([Element]\)> Function to be evaluated in browser context - `arg` <[EvaluationArgument]> Optional argument to pass to `pageFunction` @@ -763,7 +755,7 @@ const html = await page.$eval('.main-container', (e, suffix) => e.outerHTML + su Shortcut for main frame's [frame.$eval()](). -#### page.$$eval +#### method Page.$$eval - %%-query-selector-%% - `pageFunction` <[function]\([Array]<[Element]>\)> Function to be evaluated in browser context - `arg` <[EvaluationArgument]> Optional argument to pass to `pageFunction` @@ -780,10 +772,10 @@ Examples: const divsCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10); ``` -#### page.accessibility +#### namespace Page.accessibility - returns: <[Accessibility]> -#### page.addInitScript +#### method Page.addInitScript - `script` <[function]|[string]|[Object]> Script to be evaluated in the page. - `path` <[string]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). - `content` <[string]> Raw script content. @@ -808,10 +800,10 @@ const preloadFile = fs.readFileSync('./preload.js', 'utf8'); await page.addInitScript(preloadFile); ``` -> **NOTE** The order of evaluation of multiple scripts installed via [browserContext.addInitScript()]() and [page.addInitScript()]() is -not defined. +> **NOTE** The order of evaluation of multiple scripts installed via [browserContext.addInitScript()]() and +[page.addInitScript()]() is not defined. -#### page.addScriptTag +#### method Page.addScriptTag - `script` <[Object]> - `url` <[string]> URL of a script to be added. - `path` <[string]> Path to the JavaScript file to be injected into frame. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). @@ -823,7 +815,7 @@ Adds a `'); #### API reference - [class: Page](./api.md#class-page) -- [event: 'pageerror'](./api.md#event-pageerror) +- [page.on('pageerror')](./api.md#pageonpageerror)
@@ -153,6 +153,6 @@ const [popup] = await Promise.all([ #### API reference - [class: Page](./api.md#class-page) -- [event: 'requestfailed'](./api.md#event-requestfailed) -- [event: 'dialog'](./api.md#event-dialog) -- [event: 'popup'](./api.md#event-popup) +- [page.on('requestfailed')](./api.md#pageonrequestfailed) +- [page.on('dialog')](./api.md#pageondialog) +- [page.on('popup')](./api.md#pageonpopup) diff --git a/utils/doclint/check_public_api/MDBuilder.js b/utils/doclint/check_public_api/MDBuilder.js index e4752d6378..398e5e9db9 100644 --- a/utils/doclint/check_public_api/MDBuilder.js +++ b/utils/doclint/check_public_api/MDBuilder.js @@ -233,9 +233,9 @@ class MDOutline { this.errors = errors; const classHeading = /^class: (\w+)$/; const constructorRegex = /^new (\w+)\((.*)\)$/; - const methodRegex = /^(\w+)\.([\w$]+)\((.*)\)$/; + const methodRegex = /^(\w+)\.([\w$]+)\(([^']*)\)$/; const propertyRegex = /^(\w+)\.(\w+)$/; - const eventRegex = /^event: '(\w+)'$/; + const eventRegex = /^.*\.on\('(\w+)'\)$/; let currentClassName = null; let currentClassMembers = []; let currentClassComment = ''; diff --git a/utils/doclint/check_public_api/index.js b/utils/doclint/check_public_api/index.js index 614827bcea..dc47ebfeb7 100644 --- a/utils/doclint/check_public_api/index.js +++ b/utils/doclint/check_public_api/index.js @@ -102,9 +102,9 @@ function compareDocumentations(actual, expected) { const expectedClasses = Array.from(expected.classes.keys()).sort(); const classesDiff = diff(actualClasses, expectedClasses); for (const className of classesDiff.extra) - errors.push(`Non-existing class found: ${className}`); + errors.push(`Documented but not implemented class: ${className}`); for (const className of classesDiff.missing) - errors.push(`Class not found: ${className}`); + errors.push(`Implemented but not documented class: ${className}`); for (const className of classesDiff.equal) { const actualClass = actual.classes.get(className); @@ -113,9 +113,9 @@ function compareDocumentations(actual, expected) { const expectedMethods = Array.from(expectedClass.methods.keys()).sort(); const methodDiff = diff(actualMethods, expectedMethods); for (const methodName of methodDiff.extra) - errors.push(`Non-existing method found: ${className}.${methodName}()`); + errors.push(`Documented but not implemented method: ${className}.${methodName}()`); for (const methodName of methodDiff.missing) - errors.push(`Method not found: ${className}.${methodName}()`); + errors.push(`Implemented but not documented method: ${className}.${methodName}()`); for (const methodName of methodDiff.equal) { const actualMethod = actualClass.methods.get(methodName); @@ -134,9 +134,9 @@ function compareDocumentations(actual, expected) { if (argsDiff.extra.length || argsDiff.missing.length) { const text = [`Method ${className}.${methodName}() fails to describe its parameters:`]; for (const arg of argsDiff.missing) - text.push(`- Argument not found: ${arg}`); + text.push(`- Implemented but not documented argument: ${arg}`); for (const arg of argsDiff.extra) - text.push(`- Non-existing argument found: ${arg}`); + text.push(`- Documented but not implemented argument: ${arg}`); errors.push(text.join('\n')); } @@ -147,20 +147,20 @@ function compareDocumentations(actual, expected) { const expectedProperties = Array.from(expectedClass.properties.keys()).sort(); const propertyDiff = diff(actualProperties, expectedProperties); for (const propertyName of propertyDiff.extra) - errors.push(`Non-existing property found: ${className}.${propertyName}`); + errors.push(`Documented but not implemented property: ${className}.${propertyName}`); for (const propertyName of propertyDiff.missing) { if (propertyName === 'T') continue; - errors.push(`Property not found: ${className}.${propertyName}`); + errors.push(`Implemented but not documented property: ${className}.${propertyName}`); } const actualEvents = Array.from(actualClass.events.keys()).sort(); const expectedEvents = Array.from(expectedClass.events.keys()).sort(); const eventsDiff = diff(actualEvents, expectedEvents); for (const eventName of eventsDiff.extra) - errors.push(`Non-existing event found in class ${className}: '${eventName}'`); + errors.push(`Documented but not implemented event ${className}: '${eventName}'`); for (const eventName of eventsDiff.missing) - errors.push(`Event not found in class ${className}: '${eventName}'`); + errors.push(`Implemented but not documented event ${className}: '${eventName}'`); } diff --git a/utils/doclint/check_public_api/test/check-sorting/doc.md b/utils/doclint/check_public_api/test/check-sorting/doc.md index 9b3162824a..0c97192b34 100644 --- a/utils/doclint/check_public_api/test/check-sorting/doc.md +++ b/utils/doclint/check_public_api/test/check-sorting/doc.md @@ -1,12 +1,12 @@ ### class: Foo -#### event: 'c' +#### foo.on('c') -#### event: 'a' +#### foo.on('a') #### foo.aaa() -#### event: 'b' +#### foo.on('b') #### foo.ddd diff --git a/utils/doclint/check_public_api/test/diff-arguments/result.txt b/utils/doclint/check_public_api/test/diff-arguments/result.txt index bd6b1f0eb1..2fcfe77331 100644 --- a/utils/doclint/check_public_api/test/diff-arguments/result.txt +++ b/utils/doclint/check_public_api/test/diff-arguments/result.txt @@ -1,4 +1,4 @@ [MarkDown] Heading arguments for "foo.test(...files)" do not match described ones, i.e. "...files" != "...filePaths" [MarkDown] Method Foo.foo() fails to describe its parameters: -- Argument not found: arg3 -- Non-existing argument found: arg2 \ No newline at end of file +- Implemented but not documented argument: arg3 +- Documented but not implemented argument: arg2 \ No newline at end of file diff --git a/utils/doclint/check_public_api/test/diff-classes/result.txt b/utils/doclint/check_public_api/test/diff-classes/result.txt index 2852a437c6..37e0cbf023 100644 --- a/utils/doclint/check_public_api/test/diff-classes/result.txt +++ b/utils/doclint/check_public_api/test/diff-classes/result.txt @@ -1,3 +1,3 @@ -[MarkDown] Non-existing class found: Bar -[MarkDown] Non-existing class found: Baz -[MarkDown] Class not found: Other \ No newline at end of file +[MarkDown] Documented but not implemented class: Bar +[MarkDown] Documented but not implemented class: Baz +[MarkDown] Implemented but not documented class: Other \ No newline at end of file diff --git a/utils/doclint/check_public_api/test/diff-events/doc.md b/utils/doclint/check_public_api/test/diff-events/doc.md index 3da9c79511..44249e2394 100644 --- a/utils/doclint/check_public_api/test/diff-events/doc.md +++ b/utils/doclint/check_public_api/test/diff-events/doc.md @@ -1,5 +1,5 @@ ### class: Foo -#### event: 'start' +#### foo.on('start') -#### event: 'stop' +#### foo.on('stop') diff --git a/utils/doclint/check_public_api/test/diff-events/result.txt b/utils/doclint/check_public_api/test/diff-events/result.txt index 8a18433aed..2584564bf6 100644 --- a/utils/doclint/check_public_api/test/diff-events/result.txt +++ b/utils/doclint/check_public_api/test/diff-events/result.txt @@ -1,2 +1,2 @@ -[MarkDown] Non-existing event found in class Foo: 'stop' -[MarkDown] Event not found in class Foo: 'finish' \ No newline at end of file +[MarkDown] Implemented but not documented event Foo: 'finish' +[MarkDown] Implemented but not documented event Foo: 'start' \ No newline at end of file diff --git a/utils/doclint/check_public_api/test/diff-methods/result.txt b/utils/doclint/check_public_api/test/diff-methods/result.txt index d919f52e99..3f1ef2fea6 100644 --- a/utils/doclint/check_public_api/test/diff-methods/result.txt +++ b/utils/doclint/check_public_api/test/diff-methods/result.txt @@ -1,3 +1,3 @@ -[MarkDown] Non-existing method found: Foo.proceed() -[MarkDown] Method not found: Foo.stop() -[MarkDown] Property not found: Foo.zzz \ No newline at end of file +[MarkDown] Documented but not implemented method: Foo.proceed() +[MarkDown] Implemented but not documented method: Foo.stop() +[MarkDown] Implemented but not documented property: Foo.zzz \ No newline at end of file diff --git a/utils/doclint/check_public_api/test/diff-properties/result.txt b/utils/doclint/check_public_api/test/diff-properties/result.txt index 382a4d41b8..1c3039dd53 100644 --- a/utils/doclint/check_public_api/test/diff-properties/result.txt +++ b/utils/doclint/check_public_api/test/diff-properties/result.txt @@ -1,2 +1,2 @@ -[MarkDown] Non-existing property found: Foo.c -[MarkDown] Property not found: Foo.b \ No newline at end of file +[MarkDown] Documented but not implemented property: Foo.c +[MarkDown] Implemented but not documented property: Foo.b \ No newline at end of file diff --git a/utils/doclint/check_public_api/test/md-builder-common/doc.md b/utils/doclint/check_public_api/test/md-builder-common/doc.md index 42695c4cd4..6f2d6b19eb 100644 --- a/utils/doclint/check_public_api/test/md-builder-common/doc.md +++ b/utils/doclint/check_public_api/test/md-builder-common/doc.md @@ -2,7 +2,7 @@ This is a class. -#### event: 'frame' +#### foo.on('frame') - <[Frame]> This event is dispatched. diff --git a/utils/doclint/cli.js b/utils/doclint/cli.js index 0e2550eddf..bbcf01fb28 100755 --- a/utils/doclint/cli.js +++ b/utils/doclint/cli.js @@ -59,47 +59,67 @@ async function run() { { const nodes = parseMd(renderMdTemplate(body, params)); const signatures = new Map(); - let h4; + let lastMethod; let args; - const flush = () => { - if (h4 && !['page.accessibility', 'page.mouse', 'page.keyboard', 'page.coverage', 'page.touchscreen'].includes(h4.h4)) { - const tokens = []; - let hasOptional = false; - for (const arg of args) { - const optional = arg.name === 'options' || arg.text.includes('Optional'); - if (tokens.length) { - if (optional && !hasOptional) - tokens.push(`[, ${arg.name}`); - else - tokens.push(`, ${arg.name}`); - } else { - if (optional && !hasOptional) - tokens.push(`[${arg.name}`); - else - tokens.push(`${arg.name}`); - } - hasOptional = hasOptional || optional; + const flushMethodSignature = () => { + if (!lastMethod) + return; + const tokens = []; + let hasOptional = false; + for (const arg of args) { + const optional = arg.name === 'options' || arg.text.includes('Optional'); + if (tokens.length) { + if (optional && !hasOptional) + tokens.push(`[, ${arg.name}`); + else + tokens.push(`, ${arg.name}`); + } else { + if (optional && !hasOptional) + tokens.push(`[${arg.name}`); + else + tokens.push(`${arg.name}`); } - if (hasOptional) - tokens.push(']'); - const signature = tokens.join(''); - signatures.set(h4.h4, signature); - h4.h4 = `${h4.h4}(${signature})`; + hasOptional = hasOptional || optional; } - h4 = null; + if (hasOptional) + tokens.push(']'); + const signature = tokens.join(''); + signatures.set(lastMethod.h4, signature); + lastMethod.h4 = `${lastMethod.h4}(${signature})`; + lastMethod = null; args = null; }; for (const node of nodes) { if (node.h1 || node.h2 || node.h3 || node.h4) - flush(); + flushMethodSignature(); + if (node.h4) { - h4 = node.h4.startsWith('event:') ? null : node; - args = node.h4.startsWith('event:') ? null : []; + lastMethod = null; + args = null; + let match = node.h4.match(/(event|method|namespace) (JS|CDP|[A-Z])([^.]+)\.(.*)/); + if (!match) + continue; + if (match[1] === 'event') { + node.h4 = `${match[2].toLowerCase() + match[3]}.on('${match[4]}')`; + continue; + } + + if (match[1] === 'method') { + node.h4 = `${match[2].toLowerCase() + match[3]}.${match[4]}`; + lastMethod = node; + args = []; + continue; + } + + if (match[1] === 'namespace') { + node.h4 = `${match[2].toLowerCase() + match[3]}.${match[4]}`; + continue; + } + continue; } - if (args && node.li && node.liType === 'default' && !node.li.startsWith('returns')) { + if (args && node.li && node.liType === 'default' && !node.li.startsWith('returns')) args.push(parseArgument(node.li)); - } } api.setText([comment, header, renderMd(nodes), footer].join('\n')); @@ -202,7 +222,8 @@ async function getChromeVersion() { function getRepositoryFiles() { const out = spawnSync('git', ['ls-files'], {cwd: PROJECT_DIR}); - return out.stdout.toString().trim().split('\n').map(file => path.join(PROJECT_DIR, file)); + const files = out.stdout.toString().trim().split('\n').filter(f => !f.startsWith('docs-src')); + return files.map(file => path.join(PROJECT_DIR, file)); } async function getFirefoxVersion() { diff --git a/utils/doclint/preprocessor/index.js b/utils/doclint/preprocessor/index.js index 214e8c5c54..edfa1e29c6 100644 --- a/utils/doclint/preprocessor/index.js +++ b/utils/doclint/preprocessor/index.js @@ -126,7 +126,6 @@ function autocorrectInvalidLinks(projectRoot, sources, allowedFilePaths) { } const sourceEdits = new SourceEdits(source); let offset = 0; - const edits = []; const lines = source.text().split('\n'); lines.forEach((line, lineNumber) => { @@ -192,10 +191,10 @@ function generateLinks(source, signatures, messages) { while (match = linkRegex.exec(line)) { const [, name] = match; const hrefOffset = offset + lineNumber + match.index + 3 + name.length; - const eventMatch = name.match(/.*on\('(.*)'\)/); + const eventMatch = name.match(/.*on\('.*'\)/); let replacement; if (eventMatch) { - replacement = `#event-${eventMatch[1]}`; + replacement = eventMatch[0]; } else { const method = name.substring(0, name.length - 2); let signature = signatures.get(method); @@ -204,9 +203,9 @@ function generateLinks(source, signatures, messages) { signature = '\u2026'; } sourceEdits.edit(hrefOffset - 3, hrefOffset - 3, signature); - replacement = `#${(name + signature).toLowerCase().replace(/[^a-z]/gm, '')}`; + replacement = name + signature; } - sourceEdits.edit(hrefOffset, hrefOffset, replacement); + sourceEdits.edit(hrefOffset, hrefOffset, '#' + replacement.toLowerCase().replace(/[^a-z]/gm, '')); } offset += line.length; });