docs: more jsdoc (#2058)

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
  */

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<string>} 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<string>} 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.

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<void>} 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<void>} A promise that resolves when the cache is cleared but cookies are kept.
    */

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.

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<void>} 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<void>} 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.
    */

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.

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) {

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<Object>} A promise that resolves with the screenshot details.

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<void>} 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<void>} A promise that resolves when the page complete check has finished.
    */
   async byPageToComplete() {

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<void>} A promise that resolves when the navigation and setup are
@@ -131,14 +132,16 @@ 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}
      */
     this.error = measure._error.bind(measure);
 
     /**
      * 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);

lib/core/engine/context.js

@@ -15,7 +15,7 @@
 
 /**
  * Class representing the context of a Browsertime run.
- *
+ * @hideconstructor
  * @class
  */
 export class Context {