From bb4d31f9bc47f2055e197a4b0d78d1055d46e640 Mon Sep 17 00:00:00 2001 From: Peter Hedenskog Date: Fri, 5 Jan 2024 16:55:51 +0100 Subject: [PATCH] docs: more jsdoc (#2058) --- lib/core/engine/command/addText.js | 1 - lib/core/engine/command/android.js | 2 ++ lib/core/engine/command/cache.js | 2 ++ lib/core/engine/command/chromeDevToolsProtocol.js | 7 ++++++- lib/core/engine/command/chromeTrace.js | 2 ++ lib/core/engine/command/measure.js | 7 +++++++ lib/core/engine/command/meta.js | 4 ++-- lib/core/engine/command/screenshot.js | 1 + lib/core/engine/command/wait.js | 3 ++- lib/core/engine/commands.js | 9 ++++++--- lib/core/engine/context.js | 2 +- 11 files changed, 31 insertions(+), 9 deletions(-) diff --git a/lib/core/engine/command/addText.js b/lib/core/engine/command/addText.js index 94f05123a..907447786 100644 --- a/lib/core/engine/command/addText.js +++ b/lib/core/engine/command/addText.js @@ -4,7 +4,6 @@ const log = intel.getLogger('browsertime.command.addText'); /** * Provides functionality to add text to elements on a web page using various selectors. - * @example commands.addText. * @class * @hideconstructor */ diff --git a/lib/core/engine/command/android.js b/lib/core/engine/command/android.js index cda7bdb75..48e67a6a6 100644 --- a/lib/core/engine/command/android.js +++ b/lib/core/engine/command/android.js @@ -20,6 +20,7 @@ export class AndroidCommand { * This method requires the Android device to be properly configured. * * @async + * @example await commands.android.shell(''); * @param {string} command - The shell command to run on the Android device. * @returns {Promise} A promise that resolves with the result of the command or rejects if there's an error. * @throws {Error} Throws an error if Android is not configured or if the command fails. @@ -43,6 +44,7 @@ export class AndroidCommand { * rooted the device. * * @async + * @example await commands.android.shellAsRoot(''); * @param {string} command - The shell command to run on the Android device as root. * @returns {Promise} A promise that resolves with the result of the command or rejects if there's an error. * @throws {Error} Throws an error if Android is not configured or if the command fails. diff --git a/lib/core/engine/command/cache.js b/lib/core/engine/command/cache.js index d6eea7e20..d1bc0ff42 100644 --- a/lib/core/engine/command/cache.js +++ b/lib/core/engine/command/cache.js @@ -35,6 +35,7 @@ export class Cache { * If the browser is not supported, logs an error message. * * @async + * @example await commands.cache.clear(); * @throws Will throw an error if the browser is not supported. * @returns {Promise} A promise that resolves when the cache and cookies are cleared. */ @@ -62,6 +63,7 @@ export class Cache { * If the browser is not supported, logs an error message. * * @async + * @example await commands.cache.clearKeepCookies(); * @throws Will throw an error if the browser is not supported. * @returns {Promise} A promise that resolves when the cache is cleared but cookies are kept. */ diff --git a/lib/core/engine/command/chromeDevToolsProtocol.js b/lib/core/engine/command/chromeDevToolsProtocol.js index 9bb899b15..fccb50d89 100644 --- a/lib/core/engine/command/chromeDevToolsProtocol.js +++ b/lib/core/engine/command/chromeDevToolsProtocol.js @@ -54,6 +54,8 @@ export class ChromeDevelopmentToolsProtocol { * Sends a command to the DevTools Protocol and returns the result. * * @async + * @example const domCounters = await commands.cdp.sendAndGet('Memory.getDOMCounters'); + * @see https://chromedevtools.github.io/devtools-protocol/ * @param {string} command - The DevTools Protocol command to send. * @param {Object} arguments_ - The arguments for the command. * @throws {Error} Throws an error if the browser is not supported or if the command fails. @@ -83,9 +85,10 @@ export class ChromeDevelopmentToolsProtocol { /** * Retrieves the raw client for the DevTools Protocol. - * + * @example const cdpClient = commands.cdp.getRawClient(); * @returns {Object} The raw DevTools Protocol client. * @throws {Error} Throws an error if the browser is not supported. + * @see https://github.com/cyrus-and/chrome-remote-interface */ getRawClient() { if (this.browserName === 'chrome' || this.browserName === 'edge') { @@ -99,6 +102,8 @@ export class ChromeDevelopmentToolsProtocol { * Sends a command to the DevTools Protocol. * * @async + * @example await commands.cdp.send(''); + * @see https://chromedevtools.github.io/devtools-protocol/ * @param {string} command - The DevTools Protocol command to send. * @param {Object} arguments_ - The arguments for the command. * @throws {Error} Throws an error if the browser is not supported or if the command fails. diff --git a/lib/core/engine/command/chromeTrace.js b/lib/core/engine/command/chromeTrace.js index f3aaf95e2..f5f8d3b8c 100644 --- a/lib/core/engine/command/chromeTrace.js +++ b/lib/core/engine/command/chromeTrace.js @@ -34,6 +34,7 @@ export class ChromeTrace { * Starts the Chrome trace collection. * * @async + * @example await commands.trace.start(); * @returns {Promise} A promise that resolves when tracing is started. * @throws {Error} Throws an error if not running Chrome or if configuration is not set for custom tracing. */ @@ -55,6 +56,7 @@ export class ChromeTrace { * Stops the Chrome trace collection, processes the collected data, and attaches it to the result object. * * @async + * @example await commands.trace.stop(); * @returns {Promise} A promise that resolves when tracing is stopped and data is processed. * @throws {Error} Throws an error if not running Chrome or if custom tracing was not started. */ diff --git a/lib/core/engine/command/measure.js b/lib/core/engine/command/measure.js index ce05919d3..8635eb771 100644 --- a/lib/core/engine/command/measure.js +++ b/lib/core/engine/command/measure.js @@ -272,6 +272,13 @@ export class Measure { * If an alias is provided, or no URL is available, it sets up the environment for a user-driven navigation. * * @async + * @example + * await commands.measure.start('https://www.example.org'); + * // Or start the measurement and click on a link + * await commands.measure.start(); + * await commands.click.byLinkTextAndWait('Documentation'); + * // Remember to stop the measurements if you do not provide a URL + * await commands.measure.stop(); * @param {string} urlOrAlias - The URL to navigate to, or an alias representing the test. * @param {string} [optionalAlias] - An optional alias that can be used if the first parameter is a URL. * @throws {Error} Throws an error if navigation fails or if there are issues in the setup process. diff --git a/lib/core/engine/command/meta.js b/lib/core/engine/command/meta.js index 4d8eb6442..7a231dadd 100644 --- a/lib/core/engine/command/meta.js +++ b/lib/core/engine/command/meta.js @@ -9,7 +9,7 @@ export class Meta { /** * Sets the description for the user journey. - * + * @example commands.meta.setDescription('My test'); * @param {string} text - The text to set as the description. */ setDescription(text) { @@ -18,7 +18,7 @@ export class Meta { /** * Sets the title for the user journey. - * + * @example commands.meta.setTitle('Test title'); * @param {string} text - The text to set as the title. */ setTitle(text) { diff --git a/lib/core/engine/command/screenshot.js b/lib/core/engine/command/screenshot.js index 703702f91..9232de41f 100644 --- a/lib/core/engine/command/screenshot.js +++ b/lib/core/engine/command/screenshot.js @@ -28,6 +28,7 @@ export class Screenshot { * Takes a screenshot and saves it using the screenshot manager. * * @async + * @example async commands.screenshot.take('my_startpage'); * @param {string} name The name to assign to the screenshot file. * @throws {Error} Throws an error if the name parameter is not provided. * @returns {Promise} A promise that resolves with the screenshot details. diff --git a/lib/core/engine/command/wait.js b/lib/core/engine/command/wait.js index a565ad75f..de5dd037f 100644 --- a/lib/core/engine/command/wait.js +++ b/lib/core/engine/command/wait.js @@ -108,6 +108,7 @@ export class Wait { * Waits for a specified amount of time. * * @async + * @example async commands.wait.byTime(1000); * @param {number} ms - The time in milliseconds to wait. * @returns {Promise} A promise that resolves when the specified time has elapsed. */ @@ -117,8 +118,8 @@ export class Wait { /** * Waits for the page to finish loading. - * * @async + * @example async commands.wait.byPageToComplete(); * @returns {Promise} A promise that resolves when the page complete check has finished. */ async byPageToComplete() { diff --git a/lib/core/engine/commands.js b/lib/core/engine/commands.js index 134c5a91c..bbb750d68 100644 --- a/lib/core/engine/commands.js +++ b/lib/core/engine/commands.js @@ -27,7 +27,7 @@ import { GeckoProfiler } from '../../firefox/geckoProfiler.js'; import { GeckoProfiler as GeckoProfilerCommand } from './command/geckoProfiler.js'; /** * Represents the set of commands available in a Browsertime script. - * + * @hideconstructor */ export class Commands { constructor( @@ -115,8 +115,9 @@ export class Commands { /** * Navigates to a specified URL and handles additional setup for a page visit. - * @type {Function} * @async + * @example await commands.navigate('https://www.example.org'); + * @type {Function} * @param {string} url - The URL to navigate to. * @throws {Error} Throws an error if navigation or setup fails. * @returns {Promise} A promise that resolves when the navigation and setup are @@ -131,6 +132,7 @@ export class Commands { /** * Add a text that will be an error attached to the current page. + * @example await commands.error('My error message'); * @param {string} message - The error message. * @type {Function} */ @@ -138,7 +140,8 @@ export class Commands { /** * Mark this run as an failure. Add a message that explains the failure. - * @param {string} message - The message attached as a failure. + * @example await commands.markAsFailure('My failure message'); + * @param {string} message - The message attached as a failure * @type {Function} */ this.markAsFailure = measure._failure.bind(measure); diff --git a/lib/core/engine/context.js b/lib/core/engine/context.js index 61f3c820c..9fba6b3e3 100644 --- a/lib/core/engine/context.js +++ b/lib/core/engine/context.js @@ -15,7 +15,7 @@ /** * Class representing the context of a Browsertime run. - * + * @hideconstructor * @class */ export class Context {