quine-global/webdriverio
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: migrate from dox to comment-parser (#14369)

Browse source
This commit is contained in:
Rondley Gregório 2025-04-04 22:08:07 -03:00 committed by GitHub
parent 1d77f28589
commit 7c9dd9a48d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
27 changed files with 246 additions and 272 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
package.json
View file

@ -98,9 +98,9 @@
"chalk": "^5.3.0",
"cheerio": "1.0.0",
"cli-highlight": "^2.1.11",
"comment-parser": "^1.4.1",
"copyfiles": "^2.4.1",
"depcheck": "^1.4.7",
"dox": "^1.0.0",
"ejs": "^3.1.10",
"ejs-lint": "^2.0.0",
"eta": "^3.4.0",

2
packages/webdriverio/src/commands/browser/getWindowSize.ts
View file

@ -19,7 +19,7 @@ interface BrowserSize {
* </example>
*
* @alias browser.getWindowSize
* @return {Object} { x, y, width, height } for W3C or { width, height } for non W3C browser
* @return {Object} `{ x, y, width, height }` for W3C or `{ width, height }` for non W3C browser
* @type window
*
*/

4
packages/webdriverio/src/commands/browser/newWindow.ts
View file

@ -61,9 +61,7 @@ const WAIT_FOR_NEW_HANDLE_TIMEOUT = 3000
* @param {String=} options.windowName name of the new window
* @param {String=} options.windowFeatures features of opened window (e.g. size, position, scrollbars, etc.)
*
* @return {Object} An object containing the window handle and the type of new window
* @return {String} handle - The ID of the window handle of the new tab or window
* @return {String} type - The type of the new window, either 'tab' or 'window'
* @return {Object} An object containing the window handle and the type of new window `{handle: string, type: string}` handle - The ID of the window handle of the new tab or window, type - The type of the new window, either 'tab' or 'window'
*
* @throws {Error} If `url` is invalid, if the command is used on mobile, or `type` is not 'tab' or 'window'.
*

2
packages/webdriverio/src/commands/browser/react$$.ts
View file

@ -35,7 +35,7 @@ import type { ReactSelectorOptions } from '../../types.js'
* @param {string} selector of React component
* @param {ReactSelectorOptions=} options React selector options
* @param {Object=} options.props React props the element should contain
* @param {Array<any>|number|string|object|boolean=} options.state React state the element should be in
* @param {`Array<any>|number|string|object|boolean`=} options.state React state the element should be in
* @return {ElementArray}
*
*/

2
packages/webdriverio/src/commands/browser/react$.ts
View file

@ -44,7 +44,7 @@ import type { ReactSelectorOptions } from '../../types.js'
* @param {string} selector of React component
* @param {ReactSelectorOptions=} options React selector options
* @param {Object=} options.props React props the element should contain
* @param {Array<any>|number|string|object|boolean=} options.state React state the element should be in
* @param {`Array<any>|number|string|object|boolean`=} options.state React state the element should be in
* @return {Element}
*
*/

2
packages/webdriverio/src/commands/browser/reloadSession.ts
View file

@ -51,7 +51,7 @@ const log = logger('webdriverio')
* </example>
*
* @alias browser.reloadSession
* @param newCapabilities new capabilities to create a session with
* @param {WebdriverIO.Capabilities=} newCapabilities new capabilities to create a session with
* @type utility
*
*/

2
packages/webdriverio/src/commands/browser/setCookies.ts
View file

@ -41,7 +41,7 @@ import type { Cookie } from '@wdio/protocols'
* </example>
*
* @alias browser.setCookies
* @param {Array<WebDriverCookie>|WebDriverCookie} cookie cookie object or object array.
* @param {`Array<WebDriverCookie>|WebDriverCookie`} cookie cookie object or object array.
* @param {String=} cookie.name The name of the cookie.
* @param {String=} cookie.value The cookie value.
* @param {String=} cookie.path The cookie path. Defaults to "/" if omitted when adding a cookie.

2
packages/webdriverio/src/commands/browser/setViewport.ts
View file

@ -30,7 +30,7 @@ export interface SetViewportOptions {
* @param {number} options.width viewport width in pixels
* @param {number} options.height viewport height in pixels
* @param {number} options.devicePixelRatio pixel ratio of the viewport
* @return {Promise<void>}
* @return {`Promise<void>`}
* @type window
*/
export async function setViewport(

2
packages/webdriverio/src/commands/browser/setWindowSize.ts
View file

@ -19,7 +19,7 @@ const maxWindowSize = Number.MAX_SAFE_INTEGER
* @alias browser.setWindowSize
* @param {number} width browser will be resized to provided width
* @param {number} height browser will be resized to provided height
* @return {Null|Object} Null for *NO*W3C browser and Object{x, y, width, height} for W3C browser
* @return {Null|Object} Null for *NO*W3C browser and Object `{x, y, width, height}` for W3C browser
* @type window
*
*/

2
packages/webdriverio/src/commands/browser/switchFrame.ts
View file

@ -63,7 +63,7 @@ const log = logger('webdriverio:switchFrame')
*
* @alias browser.switchFrame
* @param {string|object|function} context
* @returns {Promise<string>} the current active context id
* @returns {`Promise<string>`} the current active context id
*/
export async function switchFrame (
this: WebdriverIO.Browser,

6
packages/webdriverio/src/commands/browser/url.ts
View file

@ -136,13 +136,13 @@ const DEFAULT_WAIT_STATE = 'complete'
*
* @param {string=} url the URL to navigate to
* @param {UrlOptions=} options navigation options
* @param {'none' | 'interactive' | 'networkIdle' | 'complete'} options.wait The desired state the requested resource should be in before finishing the command. Default: 'complete'
* @param {'none'|'interactive'|'networkIdle'|'complete'} [options.wait] The desired state the requested resource should be in before finishing the command. Default: 'complete'
* @param {number=} options.timeout If set to a number, the command will wait for the specified amount of milliseconds for the page to load
* all responses before returning. Default: 5000
* @param {Function=} options.onBeforeLoad A function that is being called before your page has loaded all of its resources. It allows you to easily
* mock the environment, e.g. overwrite Web APIs that your application uses.
* @param {{user: string, pass: string}=} options.auth basic authentication credentials
* @param {Record<string, string>=} options.headers headers to be sent with the request
* @param {`{user: string, pass: string}`=} options.auth basic authentication credentials
* @param {`Record<string, string>`=} options.headers headers to be sent with the request
* @returns {WebdriverIO.Request} a request object of the page load with information about the request and response data
*
* @see https://w3c.github.io/webdriver/webdriver-spec.html#dfn-get

2
packages/webdriverio/src/commands/clock/restore.ts
View file

@ -14,6 +14,6 @@
* </example>
*
* @alias clock.restore
* @returns { Promise<void> }
* @returns { `Promise<void>` }
*/
// actual implementation is located in packages/webdriverio/src/clock.ts

2
packages/webdriverio/src/commands/clock/setSystemTime.ts
View file

@ -13,6 +13,6 @@
*
* @alias clock.setSystemTime
* @param { Date | number } date The new date to set the system time to.
* @returns { Promise<void> }
* @returns { `Promise<void>` }
*/
// actual implementation is located in packages/webdriverio/src/clock.ts

2
packages/webdriverio/src/commands/clock/tick.ts
View file

@ -12,7 +12,7 @@
*
* @alias clock.tick
* @param { number } ms The number of milliseconds to move the clock.
* @returns { Promise<void> }
* @returns { `Promise<void>` }
*/
// actual implementation is located in packages/webdriverio/src/clock.ts

2
packages/webdriverio/src/commands/element/addValue.ts
View file

@ -24,7 +24,7 @@ const VALID_TYPES = ['string', 'number']
* </example>
*
* @alias element.addValue
* @param {string | number} value value to be added
* @param {string|number} value value to be added
*
*/
export function addValue (

2
packages/webdriverio/src/commands/element/click.ts
View file

@ -100,7 +100,7 @@ const log = logger('webdriver')
* @uses protocol/element, protocol/elementIdClick, protocol/performActions, protocol/positionClick
* @type action
* @param {ClickOptions=} options Click options (optional)
* @param {string= | number=} options.button Can be one of `[0, "left", 1, "middle", 2, "right"]` <br /><strong>WEB-ONLY</strong> (Desktop/Mobile)
* @param {string|number=} options.button Can be one of `[0, "left", 1, "middle", 2, "right"]` <br /><strong>WEB-ONLY</strong> (Desktop/Mobile)
* @param {number=} options.x Clicks X horizontal pixels away from location of the element (from center point of element)<br /><strong>WEB and Native</strong> (Desktop/Mobile)
* @param {number=} options.y Clicks Y vertical pixels away from location of the element (from center point of element)<br /><strong>WEB and Native support</strong> (Desktop/Mobile)
* @param {boolean=} options.skipRelease Boolean (optional) <br /><strong>WEB-ONLY</strong> (Desktop/Mobile)

2
packages/webdriverio/src/commands/element/getLocation.ts
View file

@ -30,7 +30,7 @@ export function getLocation (this: WebdriverIO.Element, prop?: keyof Location):
*
* @alias element.getLocation
* @param {string} prop can be "x" or "y" to get a result value directly for easier assertions
* @return {Object|Number} The X and Y coordinates for the element on the page (`{x:number, y:number}`)
* @return {Object|Number} The X and Y coordinates for the element on the page `{x:number, y:number}`
* @uses protocol/elementIdLocation
* @type property
*/

2
packages/webdriverio/src/commands/element/react$$.ts
View file

@ -36,7 +36,7 @@ import type { ReactSelectorOptions } from '../../types.js'
* @param {string} selector of React component
* @param {ReactSelectorOptions=} options React selector options
* @param {Object=} options.props React props the element should contain
* @param {Array<any>|number|string|object|boolean=} options.state React state the element should be in
* @param {`Array<any>|number|string|object|boolean`=} options.state React state the element should be in
* @return {ElementArray}
*
*/

2
packages/webdriverio/src/commands/element/react$.ts
View file

@ -45,7 +45,7 @@ import type { ReactSelectorOptions } from '../../types.js'
* @param {string} selector of React component
* @param {ReactSelectorOptions=} options React selector options
* @param {Object=} options.props React props the element should contain
* @param {Array<any>|number|string|object|boolean=} options.state React state the element should be in
* @param {`Array<any>|number|string|object|boolean`=} options.state React state the element should be in
* @return {Element}
*
*/

2
packages/webdriverio/src/commands/element/setValue.ts
View file

@ -21,7 +21,7 @@
* </example>
*
* @alias element.setValue
* @param {string | number} value value to be added
* @param {string|number} value value to be added
*
*/
export async function setValue (

2
packages/webdriverio/src/commands/element/waitUntil.ts
View file

@ -13,7 +13,7 @@
* A common example is to wait until a certain element contains a certain text (see example).
*
* @alias element.waitUntil
* @param {Function#Boolean} condition condition to wait on
* @param {Function} condition condition to wait on
* @param {WaitUntilOptions=} options command options
* @param {Number=} options.timeout time in ms (default set based on [`waitforTimeout`](/docs/configuration#waitfortimeout) config value)
* @param {String=} options.timeoutMsg error message to throw when waitUntil times out

4
packages/webdriverio/src/commands/mock/request.ts
View file

@ -24,8 +24,8 @@
*
* @alias mock.request
* @param {MockOverwrite} overwrites payload to overwrite the response
* @param {Record<string,string>} overwrites.header overwrite specific headers
* @param {Record<string,string>} overwrites.cookies overwrite request cookies
* @param {`Record<string,string>`} overwrites.header overwrite specific headers
* @param {`Record<string,string>`} overwrites.cookies overwrite request cookies
* @param {string} overwrites.method overwrite request method
* @param {string} overwrites.url overwrite request url to initiate a redirect
* @param {MockResponseParams=} params additional respond parameters to overwrite

4
packages/webdriverio/src/commands/mock/requestOnce.ts
View file

@ -24,8 +24,8 @@
*
* @alias mock.requestOnce
* @param {MockOverwrite} overwrites payload to overwrite the response
* @param {Record<string, string>} overwrites.header overwrite specific headers
* @param {Record<string, string>} overwrites.cookies overwrite request cookies
* @param {`Record<string, string>`} overwrites.header overwrite specific headers
* @param {`Record<string, string>`} overwrites.cookies overwrite request cookies
* @param {string} overwrites.method overwrite request method
* @param {string} overwrites.url overwrite request url to initiate a redirect
* @param {MockResponseParams=} params additional respond parameters to overwrite

193
pnpm-lock.yaml
View file

@ -110,15 +110,15 @@ importers:
cli-highlight:
specifier: ^2.1.11
version: 2.1.11
comment-parser:
specifier: ^1.4.1
version: 1.4.1
copyfiles:
specifier: ^2.4.1
version: 2.4.1
depcheck:
specifier: ^1.4.7
version: 1.4.7
dox:
specifier: ^1.0.0
version: 1.0.0
ejs:
specifier: ^3.1.10
version: 3.1.10
@ -440,7 +440,7 @@ importers:
version: 5.2.1(vite@5.4.16(@types/node@20.17.30)(terser@5.37.0))(vue@3.5.13(typescript@5.7.3))
expect-webdriverio:
specifier: 5.1.0
version: 5.1.0(@wdio/globals@9.12.2(@wdio/logger@9.4.4)(puppeteer-core@23.11.1))(@wdio/logger@9.4.4)(webdriverio@9.12.2(puppeteer-core@23.11.1))
version: 5.1.0(@wdio/globals@9.12.3(@wdio/logger@9.4.4)(puppeteer-core@23.11.1))(@wdio/logger@9.4.4)(webdriverio@9.12.3(puppeteer-core@23.11.1))
mocha:
specifier: ^10.2.0
version: 10.8.2
@ -939,7 +939,7 @@ importers:
optionalDependencies:
expect-webdriverio:
specifier: ^5.1.0
version: 5.1.0(@wdio/globals@9.12.2(@wdio/logger@9.4.4)(puppeteer-core@23.11.1))(@wdio/logger@9.4.4)(webdriverio@packages+webdriverio)
version: 5.1.0(@wdio/globals@9.12.3(@wdio/logger@9.4.4)(puppeteer-core@23.11.1))(@wdio/logger@9.4.4)(webdriverio@packages+webdriverio)
webdriverio:
specifier: workspace:*
version: link:../webdriverio
@ -963,7 +963,7 @@ importers:
version: link:../wdio-utils
expect-webdriverio:
specifier: ^5.1.0
version: 5.1.0(@wdio/globals@packages+wdio-globals)(@wdio/logger@packages+wdio-logger)(webdriverio@9.12.2(puppeteer-core@23.11.1))
version: 5.1.0(@wdio/globals@packages+wdio-globals)(@wdio/logger@packages+wdio-logger)(webdriverio@9.12.3(puppeteer-core@23.11.1))
jasmine:
specifier: ^5.0.0
version: 5.6.0
@ -4017,12 +4017,6 @@ packages:
cpu: [x64]
os: [win32]
'@eslint-community/eslint-utils@4.4.1':
resolution: {integrity: sha512-s3O3waFUrMV8P/XaF/+ZTp1X9XBZW1a4B97ZnjQF2KYWaFD2A8KyFBsrsfSjEmjn3RGWAIuvlneuZm3CUK3jbA==}
engines: {node: ^12.22.0 || ^14.17.0 || >=16.0.0}
peerDependencies:
eslint: ^6.0.0 || ^7.0.0 || >=8.0.0
'@eslint-community/eslint-utils@4.5.1':
resolution: {integrity: sha512-soEIOALTfTK6EjmKMMoLugwaP0rzkad90iIWd1hMO9ARkSAyjfMfkRRhLvD5qH7vvM0Cg72pieUfR6yh6XxC4w==}
engines: {node: ^12.22.0 || ^14.17.0 || >=16.0.0}
@ -4057,10 +4051,6 @@ packages:
resolution: {integrity: sha512-o0bhxnL89h5Bae5T318nFoFzGy+YE5i/gGkoPAgkmTVdRKTiv3p8JHevPiPaMwoloKfEiiaHlawCqaZMqRm+XQ==}
engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
'@eslint/plugin-kit@0.2.4':
resolution: {integrity: sha512-zSkKow6H5Kdm0ZUQUB2kV5JIXqoG0+uH5YADhaEHswm664N9Db8dXSi0nMJpacpMf+MyyglF1vnZohpEg5yUtg==}
engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
'@eslint/plugin-kit@0.2.8':
resolution: {integrity: sha512-ZAoA40rNMPwSm+AeHpCq8STiNAwzWLJuP8Xv4CHIc9wv/PSuExjMrmjfYNj682vW0OOiZ1HKxzvjQr9XZIisQA==}
engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
@ -5928,8 +5918,8 @@ packages:
engines: {node: '>=18.20.0'}
hasBin: true
'@wdio/config@9.12.2':
resolution: {integrity: sha512-xm9ggKfR6jQtnkk7YXfRyUUwJEIjRhy/EgP34zaU7Gy6tNq+bsp07HsQIlrz6PXzkQv+Z+VjlK+w9szudykJqQ==}
'@wdio/config@9.12.3':
resolution: {integrity: sha512-xPLrwIm043OQkWZSlErR0e4LNYPMaLFAyDEtVEcbXgRhOH/Nl91kCUPiJMQSXJIoQ+qRxoMQzDvv01mQrcVwCA==}
engines: {node: '>=18.20.0'}
'@wdio/config@9.4.3':
@ -5939,8 +5929,8 @@ packages:
'@wdio/eslint@0.1.1':
resolution: {integrity: sha512-ZL774/0QCwnUWFgIY6vlSBH6ZVBoMYS+GIl5VMjiTO0ayp6OfN2yVkWUTmqv7gPhjJlR3zI335ho8d6J5VMF2g==}
'@wdio/globals@9.12.2':
resolution: {integrity: sha512-zx/saq1qsThElECALs+lZNRzK6cF902HIK7gSkH3PZmAKNZWGEltwaLrxWemKQq6pms28kZ8BV0LoJhztizpOg==}
'@wdio/globals@9.12.3':
resolution: {integrity: sha512-LR0RgsiMGnPGwhSaUdL5UUW0vL9Z/HJ0YtP1HgSktmGcnD1MdJYJtWTD43lwVZGg23oPMs5K3k+ftM5s9IhnWQ==}
engines: {node: '>=18.20.0'}
'@wdio/globals@9.4.3':
@ -5955,8 +5945,8 @@ packages:
resolution: {integrity: sha512-BXx8RXFUW2M4dcO6t5Le95Hi2ZkTQBRsvBQqLekT2rZ6Xmw8ZKZBPf0FptnoftFGg6dYmwnDidYv/0+4PiHjpQ==}
engines: {node: '>=18.20.0'}
'@wdio/protocols@9.12.2':
resolution: {integrity: sha512-XuHs4B81svXis8Bolyvvvf+HFsZthI9tp14CHZcnslYuafPG8kbAtUB/gFj+MIXGCML91Fbw+TNCs3eWtyY8vg==}
'@wdio/protocols@9.12.3':
resolution: {integrity: sha512-M4K8/YuVUvp6h7LflD0jNM56BnZyntoMhKSYB/4bSauVmEQKrbKh1iOZ7zYdp9R7oojjsiVspjLMN0L313JKiA==}
'@wdio/protocols@9.2.2':
resolution: {integrity: sha512-0GMUSHCbYm+J+rnRU6XPtaUgVCRICsiH6W5zCXpePm3wLlbmg/mvZ+4OnNErssbpIOulZuAmC2jNmut2AEfWSw==}
@ -5969,16 +5959,16 @@ packages:
resolution: {integrity: sha512-kchPRhoG/pCn4KhHGiL/ocNhdpR8OkD2e6sANlSUZ4TGBVi86YSIEjc2yXUwLacHknC/EnQk/SFnqd4MsNjGGg==}
engines: {node: '>=18.20.0'}
'@wdio/types@9.12.2':
resolution: {integrity: sha512-nlsSLtE70y8Jx0GA91X+q6da5JfoH//VLLAqqQnMG1Mjq8Cz0lLNIF0MlwsNBumHJ3HCqWEAmZyYIB3QZ7O/iQ==}
'@wdio/types@9.12.3':
resolution: {integrity: sha512-MlnQ3WG1CQAjmUmeKtv3timGR91hSsCwQW9T1kqpu0VaJ/qbw3sWgtArMqRvgWB2H6IGueqQwDQ9qHlP013w9Q==}
engines: {node: '>=18.20.0'}
'@wdio/types@9.4.3':
resolution: {integrity: sha512-ShXtWdtjmFUX1qT3c0Ldj7v9VB+2WnWpU3JxD0d+WL0W4TSQV8yFxVmwahRPvBsFO+ust4F38o6gOZEANCVhgA==}
engines: {node: '>=18.20.0'}
'@wdio/utils@9.12.2':
resolution: {integrity: sha512-/41vXFQ60v9fQAfPq1x92ST/L0qeJ+mCk/csxbEkTcqr8vQXr6WB27ntMc3jPU5ePB5CKa3E6VbS+fffMQguAA==}
'@wdio/utils@9.12.3':
resolution: {integrity: sha512-G7qpiLux89jqhzz33TvIIWaMIKIUUmmBaBH8ylCu3W/7h8i1/jPrYryOvWw75yVWl1ch4NYEo4uJey1NsJnkAQ==}
engines: {node: '>=18.20.0'}
'@wdio/utils@9.4.3':
@ -6933,14 +6923,14 @@ packages:
resolution: {integrity: sha512-i0/MaqBtdbnJ4XQs4Pmyb+oFQl+q0lsAmokVUH92SlSw4fkeAcG3bVon+Qt7hmtF+u3Het6o4VgrcY3qAoEB6w==}
engines: {node: ^12.20.0 || >=14}
commander@9.4.0:
resolution: {integrity: sha512-sRPT+umqkz90UA8M1yqYfnHlZA7fF6nSphDtxeywPZ49ysjxDQybzk13CL+mXekDRG92skbcqCLVovuCusNmFw==}
engines: {node: ^12.20.0 || >=14}
commander@9.5.0:
resolution: {integrity: sha512-KRs7WVDKg86PWiuAqhDrAQnTXZKraVcCc6vFdL14qrZ/DcWwuRo7VoiYXalXO7S5GKpqYiVEwCbgFDfxNHKJBQ==}
engines: {node: ^12.20.0 || >=14}
comment-parser@1.4.1:
resolution: {integrity: sha512-buhp5kePrmda3vhc5B9t7pUQXAb2Tnd0qgpkIhPhkHXxJpiPJ11H0ZEU0oBpJ2QztSbzG/ZxMj/CHsYJqRHmyg==}
engines: {node: '>= 12.0.0'}
common-ancestor-path@1.0.1:
resolution: {integrity: sha512-L3sHRo1pXXEqX8VU28kfgUY+YGsk09hPqZiZmLacNib6XNTCM8ubYeT7ryXQw8asB1sKgcU5lkB7ONug08aB8w==}
@ -7634,10 +7624,6 @@ packages:
resolution: {integrity: sha512-47qPchRCykZC03FhkYAhrvwU4xDBFIj1QPqaarj6mdM/hgUzfPHcpkHJOn3mJAufFeeAxAzeGsr5X0M4k6fLZQ==}
engines: {node: '>=12'}
dox@1.0.0:
resolution: {integrity: sha512-y0borLgGiqcXigOItzeBvWEPtZ5tkKMZ7MTa/9xhVCUz6sU1quXTTvbJGOLFZAu/4/nlj2Ui02A/tLqQFBXo+w==}
hasBin: true
dts-bundle-generator@9.5.1:
resolution: {integrity: sha512-DxpJOb2FNnEyOzMkG11sxO2dmxPjthoVWxfKqWYJ/bI/rT1rvTMktF5EKjAYrRZu6Z6t3NhOUZ0sZ5ZXevOfbA==}
engines: {node: '>=14.0.0'}
@ -7748,10 +7734,6 @@ packages:
entities@2.2.0:
resolution: {integrity: sha512-p92if5Nz619I0w+akJrLZH0MX0Pb5DX39XOwQTtXSdQQOaYH03S1uIQp4mhOZtAXrxq4ViO67YTiLBo2638o9A==}
entities@3.0.1:
resolution: {integrity: sha512-WiyBqoomrwMdFG1e0kqvASYfnlb0lp8M5o5Fw2OFq1hNZxxcNk8Ik0Xm7LxzBhuidnZB/UtBqVCgUz3kBOP51Q==}
engines: {node: '>=0.12'}
entities@4.5.0:
resolution: {integrity: sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==}
engines: {node: '>=0.12'}
@ -9617,11 +9599,6 @@ packages:
jsbn@1.1.0:
resolution: {integrity: sha512-4bYVV3aAMtDTTu4+xsDYa6sy9GyJ69/amsu9sYF2zqjiEoZA5xJi3BrfX3uY+/IekIu7MwdObdbDWpoZdBv3/A==}
jsdoctypeparser@9.0.0:
resolution: {integrity: sha512-jrTA2jJIL6/DAEILBEh2/w9QxCuwmvNXIry39Ay/HVfhE3o2yVV0U44blYkqdHA/OKloJEqvJy0xU+GSdE2SIw==}
engines: {node: '>=10'}
hasBin: true
jsdom@25.0.1:
resolution: {integrity: sha512-8i7LzZj7BF8uplX+ZyOlIz86V6TAsSs+np6m1kpW9u0JWi4z/1t+FzcK1aek+ybTnAC4KhBL4uXCNT0wcUIeCw==}
engines: {node: '>=18'}
@ -9808,9 +9785,6 @@ packages:
resolution: {integrity: sha512-wM1+Z03eypVAVUCE7QdSqpVIvelbOakn1M0bPDoA4SGWPx3sNDVUiMo3L6To6WWGClB7VyXnhQ4Sn7gxiJbE6A==}
engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
linkify-it@4.0.1:
resolution: {integrity: sha512-C7bfi1UZmoj8+PQx22XyeXCuBlokoyWQL5pWSP+EI6nzRylyThouddufc2c1NDIcP9k5agmN9fLpA7VNJfIiqw==}
lit-element@4.1.1:
resolution: {integrity: sha512-HO9Tkkh34QkTeUmEdNYhMT8hzLid7YlMlATSi1q4q17HE5d9mrrEHJ/o8O2D0cMi182zK1F3v7x0PWFjrhXFew==}
@ -10041,10 +10015,6 @@ packages:
resolution: {integrity: sha512-o5vL7aDWatOTX8LzaS1WMoaoxIiLRQJuIKKe2wAw6IeULDHaqbiqiggmx+pKvZDb1Sj+pE46Sn1T7lCqfFtg1Q==}
engines: {node: '>=16'}
markdown-it@13.0.1:
resolution: {integrity: sha512-lTlxriVoy2criHP0JKRhO2VDG9c2ypWCsT237eDiLqi09rmbKoUetyGHq2uOIRoRS//kfoJckS0eUzzkDR+k2Q==}
hasBin: true
markdown-table@2.0.0:
resolution: {integrity: sha512-Ezda85ToJUBhM6WGaG6veasyym+Tbs3cMAw/ZhOPqXiYsr0jgocBV3j3nx+4lk47plLlIqjwuTm/ywVI+zjJ/A==}
@ -10125,9 +10095,6 @@ packages:
mdn-data@2.0.30:
resolution: {integrity: sha512-GaqWWShW4kv/G9IEucWScBx9G1/vsFZZJUO+tD26M8J8z3Kw5RDQjaoZe03YAClgeS/SWPOcb4nkFBTEi5DUEA==}
mdurl@1.0.1:
resolution: {integrity: sha512-/sKlQJCBYVY9Ers9hqzKou4H6V5UWc/M59TH2dvkt+84itfnq7uFOMLpOiOS4ujvHP4etln18fmIxA5R5fll0g==}
media-typer@0.3.0:
resolution: {integrity: sha512-dq+qelQ9akHpcOl/gUVRTxVIOkAJ1wR3QAvb4RsVjS8oVoFjDGTc679wJYmUmknUF5HwMLOgb5O+a3KxfWapPQ==}
engines: {node: '>= 0.6'}
@ -13276,9 +13243,6 @@ packages:
engines: {node: '>=14.17'}
hasBin: true
uc.micro@1.0.6:
resolution: {integrity: sha512-8Y75pvTYkLJW2hWQHXxoqRgV7qb9B+9vFEtidML+7koHUFapnVJAZ6cKs+Qjz5Aw3aZWHMC6u0wJE3At+nSGwA==}
ufo@1.5.4:
resolution: {integrity: sha512-UsUk3byDzKd04EyoZ7U4DOlxQaD14JUKQl6/P7wiX4FNvUfm3XL246n9W5AmqwW5RSFJ27NAuM0iLscAOYUiGQ==}
@ -13683,16 +13647,16 @@ packages:
web-vitals@4.2.4:
resolution: {integrity: sha512-r4DIlprAGwJ7YM11VZp4R884m0Vmgr6EAKe3P+kO0PPj3Unqyvv59rczf6UiGcb9Z8QxZVcqKNwv/g0WNdWwsw==}
webdriver@9.12.2:
resolution: {integrity: sha512-lPvGBxMiJ5wy+pNEiYujEgLtULDcyT7dqgWax/DKuXdXECvnkjJqdrRkL18l5vn49DZhygzBM7gaEbIsUaKANA==}
webdriver@9.12.3:
resolution: {integrity: sha512-s3OXyjqOu78H0wN+8wdsvPNcs0xoKyziCt35I6sff9yzEdHwAqGxrQ79jKQqFcfDF0qukFIJ8QduTSpsEStLVw==}
engines: {node: '>=18.20.0'}
webdriver@9.4.3:
resolution: {integrity: sha512-aZrJq+FwJFrrSX18PHqFK3iEw+Pdu/cvJwgIiuur4/ffP47jrirwCqabCVaIV3eut+mJBc1nY7IV3Jd3i4MekQ==}
engines: {node: '>=18.20.0'}
webdriverio@9.12.2:
resolution: {integrity: sha512-yhbdKsTPxhFQ2Qsn+sbL3E6MNo4P+EuV+j75kJXz4SyrWIdEbnsDLvlYpF96x7bb21jwW0pCcdlUBA0DUxi1Cg==}
webdriverio@9.12.3:
resolution: {integrity: sha512-wdN6y/oZc/dAZY4dVT1Ku9nYtGUXH7SrQNZbWrmajyqZpySFAQ3HXLldkYtLgeoPNIuBIdoq3LstKDwQ0vEulQ==}
engines: {node: '>=18.20.0'}
peerDependencies:
puppeteer-core: ^22.3.0
@ -17167,11 +17131,6 @@ snapshots:
'@esbuild/win32-x64@0.25.0':
optional: true
'@eslint-community/eslint-utils@4.4.1(eslint@9.17.0(jiti@2.4.2))':
dependencies:
eslint: 9.17.0(jiti@2.4.2)
eslint-visitor-keys: 3.4.3
'@eslint-community/eslint-utils@4.5.1(eslint@9.17.0(jiti@2.4.2))':
dependencies:
eslint: 9.17.0(jiti@2.4.2)
@ -17213,10 +17172,6 @@ snapshots:
'@eslint/object-schema@2.1.5': {}
'@eslint/plugin-kit@0.2.4':
dependencies:
levn: 0.4.1
'@eslint/plugin-kit@0.2.8':
dependencies:
'@eslint/core': 0.13.0
@ -19702,11 +19657,11 @@ snapshots:
- supports-color
- utf-8-validate
'@wdio/config@9.12.2':
'@wdio/config@9.12.3':
dependencies:
'@wdio/logger': 9.4.4
'@wdio/types': 9.12.2
'@wdio/utils': 9.12.2
'@wdio/types': 9.12.3
'@wdio/utils': 9.12.3
deepmerge-ts: 7.1.5
glob: 10.4.5
import-meta-resolve: 4.1.0
@ -19741,10 +19696,10 @@ snapshots:
- supports-color
- typescript
'@wdio/globals@9.12.2(@wdio/logger@9.4.4)(puppeteer-core@23.11.1)':
'@wdio/globals@9.12.3(@wdio/logger@9.4.4)(puppeteer-core@23.11.1)':
optionalDependencies:
expect-webdriverio: 5.1.0(@wdio/globals@9.12.2(@wdio/logger@9.4.4)(puppeteer-core@23.11.1))(@wdio/logger@9.4.4)(webdriverio@9.12.2(puppeteer-core@23.11.1))
webdriverio: 9.12.2(puppeteer-core@23.11.1)
expect-webdriverio: 5.1.0(@wdio/globals@9.12.3(@wdio/logger@9.4.4)(puppeteer-core@23.11.1))(@wdio/logger@9.4.4)(webdriverio@9.12.3(puppeteer-core@23.11.1))
webdriverio: 9.12.3(puppeteer-core@23.11.1)
transitivePeerDependencies:
- '@wdio/logger'
- bare-buffer
@ -19778,7 +19733,7 @@ snapshots:
loglevel-plugin-prefix: 0.8.4
strip-ansi: 7.1.0
'@wdio/protocols@9.12.2': {}
'@wdio/protocols@9.12.3': {}
'@wdio/protocols@9.2.2': {}
@ -19790,7 +19745,7 @@ snapshots:
dependencies:
'@types/node': 20.17.30
'@wdio/types@9.12.2':
'@wdio/types@9.12.3':
dependencies:
'@types/node': 20.17.30
@ -19798,11 +19753,11 @@ snapshots:
dependencies:
'@types/node': 20.17.17
'@wdio/utils@9.12.2':
'@wdio/utils@9.12.3':
dependencies:
'@puppeteer/browsers': 2.9.0
'@wdio/logger': 9.4.4
'@wdio/types': 9.12.2
'@wdio/types': 9.12.3
decamelize: 6.0.0
deepmerge-ts: 7.1.5
edgedriver: 6.1.1
@ -20894,7 +20849,7 @@ snapshots:
code-red@1.0.4:
dependencies:
'@jridgewell/sourcemap-codec': 1.5.0
'@types/estree': 1.0.6
'@types/estree': 1.0.7
acorn: 8.14.0
estree-walker: 3.0.3
periscopic: 3.1.0
@ -20952,10 +20907,10 @@ snapshots:
commander@9.1.0: {}
commander@9.4.0: {}
commander@9.5.0: {}
comment-parser@1.4.1: {}
common-ancestor-path@1.0.1: {}
common-path-prefix@3.0.0: {}
@ -21719,12 +21674,6 @@ snapshots:
dotenv@16.4.7: {}
dox@1.0.0:
dependencies:
commander: 9.4.0
jsdoctypeparser: 9.0.0
markdown-it: 13.0.1
dts-bundle-generator@9.5.1:
dependencies:
typescript: 5.7.3
@ -21847,8 +21796,6 @@ snapshots:
entities@2.2.0: {}
entities@3.0.1: {}
entities@4.5.0: {}
env-paths@2.2.1: {}
@ -22229,17 +22176,17 @@ snapshots:
eslint@9.17.0(jiti@2.4.2):
dependencies:
'@eslint-community/eslint-utils': 4.4.1(eslint@9.17.0(jiti@2.4.2))
'@eslint-community/eslint-utils': 4.5.1(eslint@9.17.0(jiti@2.4.2))
'@eslint-community/regexpp': 4.12.1
'@eslint/config-array': 0.19.1
'@eslint/core': 0.9.1
'@eslint/eslintrc': 3.2.0
'@eslint/js': 9.17.0
'@eslint/plugin-kit': 0.2.4
'@eslint/plugin-kit': 0.2.8
'@humanfs/node': 0.16.6
'@humanwhocodes/module-importer': 1.0.1
'@humanwhocodes/retry': 0.4.1
'@types/estree': 1.0.6
'@types/estree': 1.0.7
'@types/json-schema': 7.0.15
ajv: 6.12.6
chalk: 4.1.2
@ -22405,20 +22352,20 @@ snapshots:
expect-type@1.1.0: {}
expect-webdriverio@5.1.0(@wdio/globals@9.12.2(@wdio/logger@9.4.4)(puppeteer-core@23.11.1))(@wdio/logger@9.4.4)(webdriverio@9.12.2(puppeteer-core@23.11.1)):
expect-webdriverio@5.1.0(@wdio/globals@9.12.3(@wdio/logger@9.4.4)(puppeteer-core@23.11.1))(@wdio/logger@9.4.4)(webdriverio@9.12.3(puppeteer-core@23.11.1)):
dependencies:
'@vitest/snapshot': 2.1.9
'@wdio/globals': 9.12.2(@wdio/logger@9.4.4)(puppeteer-core@23.11.1)
'@wdio/globals': 9.12.3(@wdio/logger@9.4.4)(puppeteer-core@23.11.1)
'@wdio/logger': 9.4.4
expect: 29.7.0
jest-matcher-utils: 29.7.0
lodash.isequal: 4.5.0
webdriverio: 9.12.2(puppeteer-core@23.11.1)
webdriverio: 9.12.3(puppeteer-core@23.11.1)
expect-webdriverio@5.1.0(@wdio/globals@9.12.2(@wdio/logger@9.4.4)(puppeteer-core@23.11.1))(@wdio/logger@9.4.4)(webdriverio@packages+webdriverio):
expect-webdriverio@5.1.0(@wdio/globals@9.12.3(@wdio/logger@9.4.4)(puppeteer-core@23.11.1))(@wdio/logger@9.4.4)(webdriverio@packages+webdriverio):
dependencies:
'@vitest/snapshot': 2.1.9
'@wdio/globals': 9.12.2(@wdio/logger@9.4.4)(puppeteer-core@23.11.1)
'@wdio/globals': 9.12.3(@wdio/logger@9.4.4)(puppeteer-core@23.11.1)
'@wdio/logger': 9.4.4
expect: 29.7.0
jest-matcher-utils: 29.7.0
@ -22447,7 +22394,7 @@ snapshots:
lodash.isequal: 4.5.0
webdriverio: link:packages/webdriverio
expect-webdriverio@5.1.0(@wdio/globals@packages+wdio-globals)(@wdio/logger@packages+wdio-logger)(webdriverio@9.12.2(puppeteer-core@23.11.1)):
expect-webdriverio@5.1.0(@wdio/globals@packages+wdio-globals)(@wdio/logger@packages+wdio-logger)(webdriverio@9.12.3(puppeteer-core@23.11.1)):
dependencies:
'@vitest/snapshot': 2.1.9
'@wdio/globals': link:packages/wdio-globals
@ -22455,7 +22402,7 @@ snapshots:
expect: 29.7.0
jest-matcher-utils: 29.7.0
lodash.isequal: 4.5.0
webdriverio: 9.12.2(puppeteer-core@23.11.1)
webdriverio: 9.12.3(puppeteer-core@23.11.1)
expect-webdriverio@5.1.0(@wdio/globals@packages+wdio-globals)(@wdio/logger@packages+wdio-logger)(webdriverio@packages+webdriverio):
dependencies:
@ -23848,7 +23795,7 @@ snapshots:
is-reference@3.0.3:
dependencies:
'@types/estree': 1.0.6
'@types/estree': 1.0.7
is-regex@1.2.1:
dependencies:
@ -24146,8 +24093,6 @@ snapshots:
jsbn@1.1.0: {}
jsdoctypeparser@9.0.0: {}
jsdom@25.0.1:
dependencies:
cssstyle: 4.1.0
@ -24467,10 +24412,6 @@ snapshots:
lines-and-columns@2.0.4: {}
linkify-it@4.0.1:
dependencies:
uc.micro: 1.0.6
lit-element@4.1.1:
dependencies:
'@lit-labs/ssr-dom-shim': 1.2.1
@ -24717,14 +24658,6 @@ snapshots:
markdown-extensions@2.0.0: {}
markdown-it@13.0.1:
dependencies:
argparse: 2.0.1
entities: 3.0.1
linkify-it: 4.0.1
mdurl: 1.0.1
uc.micro: 1.0.6
markdown-table@2.0.0:
dependencies:
repeat-string: 1.6.1
@ -24936,8 +24869,6 @@ snapshots:
mdn-data@2.0.30: {}
mdurl@1.0.1: {}
media-typer@0.3.0: {}
memfs@3.5.3:
@ -26185,7 +26116,7 @@ snapshots:
periscopic@3.1.0:
dependencies:
'@types/estree': 1.0.6
'@types/estree': 1.0.7
estree-walker: 3.0.3
is-reference: 3.0.3
@ -28270,7 +28201,7 @@ snapshots:
'@ampproject/remapping': 2.3.0
'@jridgewell/sourcemap-codec': 1.5.0
'@jridgewell/trace-mapping': 0.3.25
'@types/estree': 1.0.6
'@types/estree': 1.0.7
acorn: 8.14.0
aria-query: 5.3.2
axobject-query: 4.1.0
@ -28693,8 +28624,6 @@ snapshots:
typescript@5.7.3: {}
uc.micro@1.0.6: {}
ufo@1.5.4: {}
uglify-js@3.19.3:
@ -29179,15 +29108,15 @@ snapshots:
web-vitals@4.2.4: {}
webdriver@9.12.2:
webdriver@9.12.3:
dependencies:
'@types/node': 20.17.30
'@types/ws': 8.18.1
'@wdio/config': 9.12.2
'@wdio/config': 9.12.3
'@wdio/logger': 9.4.4
'@wdio/protocols': 9.12.2
'@wdio/types': 9.12.2
'@wdio/utils': 9.12.2
'@wdio/protocols': 9.12.3
'@wdio/types': 9.12.3
'@wdio/utils': 9.12.3
deepmerge-ts: 7.1.5
undici: 6.21.2
ws: 8.18.1
@ -29214,16 +29143,16 @@ snapshots:
- supports-color
- utf-8-validate
webdriverio@9.12.2(puppeteer-core@23.11.1):
webdriverio@9.12.3(puppeteer-core@23.11.1):
dependencies:
'@types/node': 20.17.30
'@types/sinonjs__fake-timers': 8.1.5
'@wdio/config': 9.12.2
'@wdio/config': 9.12.3
'@wdio/logger': 9.4.4
'@wdio/protocols': 9.12.2
'@wdio/protocols': 9.12.3
'@wdio/repl': 9.4.4
'@wdio/types': 9.12.2
'@wdio/utils': 9.12.2
'@wdio/types': 9.12.3
'@wdio/utils': 9.12.3
archiver: 7.0.1
aria-query: 5.3.2
cheerio: 1.0.0
@ -29240,7 +29169,7 @@ snapshots:
rgb2hex: 0.2.5
serialize-error: 11.0.3
urlpattern-polyfill: 10.0.0
webdriver: 9.12.2
webdriver: 9.12.3
optionalDependencies:
puppeteer-core: 23.11.1
transitivePeerDependencies:

5
scripts/docs-generation/wdioDocs.ts
View file

@ -2,8 +2,7 @@
import fs from 'node:fs'
import url from 'node:url'
import path from 'node:path'
// @ts-expect-error no type definition
import dox from 'dox'
import { parse } from 'comment-parser'
import { Eta } from 'eta'
import type { NavbarItem } from '../../website/node_modules/@docusaurus/theme-common/lib/index.js'
@ -59,7 +58,7 @@ export async function generateWdioDocs (sidebars: any) {
const raw = fs.readFileSync(filepath, 'utf-8')
const data = compiler(raw)
const doc = dox.parseComments(data, { raw: true })
const doc = parse(data, { spacing: 'preserve' })
const docfile = {
filename: filepath,
javadoc: doc,

6
scripts/templates/template.eta
View file

@ -61,7 +61,7 @@ await clock.<%= it.command %>(<%= it.paramString %>)
</thead>
<tbody>
<% it.paramTags.forEach((paramTag) => { %>
<% if (paramTag.type === "rowInfo") { %>
<% if (paramTag.tag === "rowInfo") { %>
<tr>
<% if (paramTag.string.includes('::')) { %>
<% const parts = paramTag.string.split('::').map(part => part.trim()); %>
@ -72,8 +72,8 @@ await clock.<%= it.command %>(<%= it.paramString %>)
</tr>
<% } else { %>
<tr>
<td><code><var><%= paramTag.name %></var></code><% if ((!paramTag.required && typeof paramTag.optional === 'undefined') || paramTag.optional) { %><br /><span className="label labelWarning">optional</span><% } %></td>
<td><%= Array.isArray(paramTag.types) ? paramTag.types.map((type) => `<code>${type.replace(/>/g, "&gt;").replace(/</g, "&lt;")}</code>`).join(', ') : paramTag.type.split('|').join(', ').replace('(', '').replace(')', '') %></td>
<td><code><var><%= paramTag.name + (paramTag.default ? `=${paramTag.default}` : '') %></var></code><% if ((!paramTag.required && typeof paramTag.optional === 'undefined') || paramTag.optional) { %><br /><span className="label labelWarning">optional</span><% } %></td>
<td><%= paramTag.type.split('|').join(', ').replace('(', '').replace(')', '') %></td>
<td><%= paramTag.description %></td>
</tr>
<% } %>

258
scripts/utils/formatter.ts
View file

@ -1,130 +1,182 @@
/* eslint-disable @typescript-eslint/no-explicit-any */
import path from 'node:path'
interface TagType {
string: string
type: string
}
import type { Block, Spec } from 'comment-parser'
const organizationName = 'webdriverio' // Usually your GitHub org/user name.
const projectName = 'webdriverio' // Usually your repo name.
const repoUrl = `https://github.com/${organizationName}/${projectName}`
function formatObjectToString(obj: Record<string, string[]>): string {
const formattedPairs = Object.entries(obj).map(([key, valueArray]) => {
const value = valueArray[0]
return `${key}: ${value}`
})
return `&#123;${formattedPairs.join(', ')}&#125;`
interface TagType extends Spec {
string: string
}
export default function (docfile: any) {
interface Example {
file: string;
format: string;
code: string;
}
function normalizeSpec(spec: Spec): TagType {
const ensureType = (currentType: string | undefined) => currentType || 'any'
const trimDescription = (desc: string) =>
desc && desc.endsWith('\n') ? desc.replace(/(\n)+$/, '') : desc
const string = spec.source[0].source.split(`@${spec.tag}`)[1].trim()
spec.type = ensureType(spec.type)
spec.description = trimDescription(spec.description)
return {
...spec,
string,
}
}
export default function (docfile: {
filename: string;
javadoc: Block[];
}) {
const javadoc = docfile.javadoc[0]
let type = (javadoc.ctx && javadoc.ctx.type)
let type = ''
const name = path.basename(path.basename(docfile.filename, '.js'), '.ts')
const scope = docfile.filename.split('/').slice(-2, -1)[0]
let description = ''
const paramStr: string[] = []
const propertyTags: string[] = []
const paramTags: string[] = []
const returnTags: string[] = []
const throwsTags: string[] = []
const propertyTags: TagType[] = []
const paramTags: TagType[] = []
const returnTags: TagType[] = []
const throwsTags: TagType[] = []
const fires: string[] = []
const listens: string[] = []
const exampleReferences: string[] = []
let tagDeprecated = false
let tagSee = ''
let tagVersion = ''
let tagAuthor = ''
let tagType = ''
let tagCustomType = ''
let tagMobileElement = false
let tagSkipUsage = false
let returns
for (const tag of javadoc.tags) {
if (tag.type === 'param') {
if (!Array.isArray(tag.types)) {
tag.joinedTypes = 'any'
} else {
const firstType = tag.types[0]
const newTag = normalizeSpec(tag)
const { tag: tagName, type: tagType, description, string, source } = newTag
const typeOnToken = source[0].tokens.type
if (firstType && typeof firstType === 'object') {
tag.joinedTypes = tag.types.map((item: Record<string, string[]>) => formatObjectToString(item)).join('|')
tag.types = [tag.joinedTypes]
} else {
tag.joinedTypes = tag.types.join('|').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
/**
* Handles the special case when the 'dox.parseComments' fails to compile the type correctly,
* resulting in a default string value of '[object Object]' for the elements.
* In this scenario, we fallback to using 'tag.typesDescription' to retrieve and properly format the type information.
*/
if (firstType === '[object Object]') {
tag.joinedTypes = tag.typesDescription
tag.types = tag.typesDescription.split(' | ').map((item: string) => `'${item.replace(/'/g, '')}'`)
}
}
switch (tagName) {
case 'param': {
if (tagType.includes('=')) {
newTag.optional = true
newTag.type = newTag.type.replace('=', '')
}
if (tag.typesDescription.includes('|<code>undefined</code>')) {
tag.typesDescription = `<code>${tag.joinedTypes}</code>`
} else if (tag.types.length === 1 && tag.types[0].startsWith('Record<')) {
tag.types = [tag.typesDescription.replaceAll('<code>', '').replaceAll('</code>', '')]
if (!tagType.includes('`')) {
newTag.type = `\`${newTag.type}\``
}
paramTags.push(tag)
paramStr.push(tag.name)
} else if (tag.type === 'rowInfo') {
paramTags.push(tag)
} else if (tag.type === 'property') {
tag.joinedTypes = Array.isArray(tag.types)
? tag.types.join('|').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
: 'any'
propertyTags.push(tag)
} else if (tag.type === 'return' || tag.type === 'returns') {
tag.joinedTypes = Array.isArray(tag.types)
? tag.types.join('|').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
: 'any'
returnTags.push(tag)
} else if (tag.type === 'throws') {
tag.joinedTypes = Array.isArray(tag.types)
? tag.types.join('|').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
: 'any'
throwsTags.push(tag)
} else if (tag.type === 'fires') {
fires.push(tag.string)
} else if (tag.type === 'listens') {
listens.push(tag.string)
} else if (tag.type === 'namespace') {
paramTags.push(newTag)
paramStr.push(newTag.name)
break
}
case 'rowInfo': {
paramTags.push(newTag)
break
}
case 'property': {
propertyTags.push(newTag)
break
}
case 'return':
case 'returns': {
returns = {
type: newTag.type,
name: newTag.tag,
description: string.split(typeOnToken)[1]
}
returnTags.push(newTag)
break
}
case 'throws': {
newTag.name = newTag.tag
newTag.description = string.split(typeOnToken)[1]
throwsTags.push(newTag)
break
}
case 'fires': {
fires.push(description)
break
}
case 'listens': {
listens.push(description)
break
}
case 'namespace': {
type = 'namespace'
} else if (tag.type === 'method') {
break
}
case 'method': {
type = 'method'
} else if (tag.type === 'class') {
break
}
case 'class': {
type = 'class'
} else if (tag.type === 'function') {
break
}
case 'function': {
type = 'function'
} else if (tag.type === 'event') {
break
}
case 'event': {
type = 'event'
} else if (tag.type === 'see') {
tagSee = tag.url ? tag.url : tag.local
} else if (tag.type === 'version') {
tagVersion = tag.string
} else if (tag.type === 'deprecated') {
break
}
case 'see': {
tagSee = source[0].source.split('@see')[1].trim()
break
}
case 'version': {
tagVersion = source[0].source.split('@version')[1].trim()
break
}
case 'deprecated': {
tagDeprecated = true
} else if (tag.type === 'mobileElement') {
break
}
case 'mobileElement': {
tagMobileElement = true
} else if (tag.type === 'skipUsage') {
break
}
case 'skipUsage': {
tagSkipUsage = true
} else if (tag.type === 'author') {
tagAuthor = tag.string
} else if (tag.type === 'type') {
tagType = Array.isArray(tag.types)
? tag.types.join('|').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
: 'any'
break
}
case 'author': {
tagAuthor = description
break
}
case 'type': {
tagCustomType = source[0].source.split('@type')[1].trim()
break
}
case 'example': {
exampleReferences.push(source[0].source.split('@example')[1].trim())
break
}
case 'alias':
case 'for':
case 'uses':
case 'docs': {
break
}
default:
console.log('unknown tag ', tag.tag, ' in ', docfile.filename)
break
}
}
description = javadoc.description.full
description = javadoc.description
.replace(/\nh1/, '#')
.replace(/\nh2/, '##')
.replace(/\nh3/, '###')
@ -138,28 +190,28 @@ export default function (docfile: any) {
.replace(/^h5/, '#####')
.replace(/^h6/, '######')
const files: string[] = []
const files: Example[] = []
let exampleCodeLine: string[] = []
let example: any = description.match(/<example>((.|\n)*)<\/example>/g)
const example = description.match(/<example>((.|\n)*)<\/example>/g)
let exampleFilename = ''
let currentLine = 0
if (example && example[0]) {
console.log('parse example section for', docfile.filename)
example = example[0].replace(/<(\/)*example>/g, '').split(/\n/g)
example.forEach(function(line: string) {
const exampleLines = example[0].replace(/<(\/)*example>/g, '').split(/\n/g)
exampleLines.forEach(function(line: string) {
++currentLine
const checkForFilenameExpression = line.match(/\s\s\s\s(:(\S)*\.(\S)*)/g)
if ((checkForFilenameExpression && checkForFilenameExpression.length) || (currentLine === example.length)) {
if ((checkForFilenameExpression && checkForFilenameExpression.length) || (currentLine === exampleLines.length)) {
if (exampleCodeLine.length) {
/**
* remove filename expression in first line
*/
exampleFilename = exampleCodeLine.shift()!.trim().substr(1)
exampleFilename = exampleCodeLine.shift()!.trim().slice(1)
const code = exampleCodeLine
.join('\n')
/**
@ -174,9 +226,9 @@ export default function (docfile: any) {
if (exampleFilename !== '' && code !== '') {
files.push({
file: exampleFilename,
format: exampleFilename.split(/\./).pop(),
format: exampleFilename.split(/\./).pop() || 'js',
code: code
} as any)
})
}
/**
@ -188,25 +240,21 @@ export default function (docfile: any) {
/**
* if this is the last line of code dont proceed
*/
if (currentLine === example.length) {
if (currentLine === exampleLines.length) {
return
}
}
exampleCodeLine.push(line.substr(4))
exampleCodeLine.push(line.slice(4))
})
/**
* remove example section from description
*/
description = description.substr(0, description.indexOf('<example>'))
description = description.slice(0, description.indexOf('<example>'))
}
const exampleReferences = javadoc.tags
.filter((tag: TagType) => tag.type === 'example' && typeof tag.string === 'string')
.map((tag: TagType) => tag.string)
/**
* format param strings, from
* ```
@ -234,20 +282,20 @@ export default function (docfile: any) {
throwsTags: throwsTags,
fires: fires,
listens: listens,
returns: returns,
author: tagAuthor,
version: tagVersion,
see: tagSee,
deprecated: tagDeprecated,
tagType: tagType,
type: type,
tagType: tagCustomType,
type: type ? type : false,
isMethod: type === 'method',
isFunction: type === 'function',
isClass: type === 'class',
isNamespace: type === 'namespace',
isEvent: type === 'event',
hasType: tagType !== '',
hasType: tagCustomType !== '',
description: description,
ignore: javadoc.ignore,
examples: files,
exampleReferences,
customEditUrl: `${repoUrl}/edit/main/packages/webdriverio/src/commands/${scope}/${name}.ts`,