better documentation for scripting (#2048)

lib/core/engine/command/addText.js

@@ -2,18 +2,27 @@ import { By } from 'selenium-webdriver';
 import intel from 'intel';
 const log = intel.getLogger('browsertime.command.addText');
 
+/**
+ * Provides functionality to add text to elements on a web page using various selectors.
+ *
+ * @class
+ */
 export class AddText {
   constructor(browser) {
+    /**
+     * @private
+     */
     this.browser = browser;
   }
 
   /**
-   * Add text to an element with Selenium sendKeys.
-   * @param {string} text The text string that you want to add
-   * @param {string} id The id of the element
-   * @returns {Promise} Promise object represents when the text has been
-   * added to the field
-   * @throws Will throw an error if the element is not found
+   * Adds text to an element identified by its ID.
+   *
+   * @async
+   * @param {string} text - The text string to add.
+   * @param {string} id - The ID of the element.
+   * @returns {Promise<void>} A promise that resolves when the text has been added.
+   * @throws {Error} Throws an error if the element is not found.
    */
   async byId(text, id) {
     const driver = this.browser.getDriver();
@@ -30,12 +39,13 @@ export class AddText {
   }
 
   /**
-   * Add text to an element with Selenium sendKeys.
-   * @param {string} text The text string that you want to add
-   * @param {string} xpath The xpath to the element
-   * @returns {Promise} Promise object represents when the text has been
-   * added to the field
-   * @throws Will throw an error if the element is not found
+   * Adds text to an element identified by its XPath.
+   *
+   * @async
+   * @param {string} text - The text string to add.
+   * @param {string} xpath - The XPath of the element.
+   * @returns {Promise<void>} A promise that resolves when the text has been added.
+   * @throws {Error} Throws an error if the element is not found.
    */
   async byXpath(text, xpath) {
     const driver = this.browser.getDriver();
@@ -52,12 +62,13 @@ export class AddText {
   }
 
   /**
-   * Add text to an element with Selenium sendKeys.
-   * @param {string} text The text string that you want to add
-   * @param {string} selector The CSS selector to the element
-   * @returns {Promise} Promise object represents when the text has been
-   * added to the field
-   * @throws Will throw an error if the element is not found
+   * Adds text to an element identified by its CSS selector.
+   *
+   * @async
+   * @param {string} text - The text string to add.
+   * @param {string} selector - The CSS selector of the element.
+   * @returns {Promise<void>} A promise that resolves when the text has been added.
+   * @throws {Error} Throws an error if the element is not found.
    */
   async bySelector(text, selector) {
     const driver = this.browser.getDriver();
@@ -74,12 +85,13 @@ export class AddText {
   }
 
   /**
-   * Add text to an element with Selenium sendKeys.
-   * @param {string} text The text string that you want to add
-   * @param {string} className A specific class name
-   * @returns {Promise} Promise object represents when the text has been
-   * added to the field
-   * @throws Will throw an error if the element is not found
+   * Adds text to an element identified by its class name.
+   *
+   * @async
+   * @param {string} text - The text string to add.
+   * @param {string} className - The class name of the element.
+   * @returns {Promise<void>} A promise that resolves when the text has been added.
+   * @throws {Error} Throws an error if the element is not found.
    */
   async byClassName(text, className) {
     const driver = this.browser.getDriver();
@@ -96,12 +108,13 @@ export class AddText {
   }
 
   /**
-   * Add text to an element with Selenium sendKeys.
-   * @param {string} text The text string that you want to add
-   * @param {string} name Element whose name attribute has the given value.
-   * @returns {Promise} Promise object represents when the text has been
-   * added to the field
-   * @throws Will throw an error if the element is not found
+   * Adds text to an element identified by its name attribute.
+   *
+   * @async
+   * @param {string} text - The text string to add.
+   * @param {string} name - The name attribute of the element.
+   * @returns {Promise<void>} A promise that resolves when the text has been added.
+   * @throws {Error} Throws an error if the element is not found.
    */
   async byName(text, name) {
     const driver = this.browser.getDriver();

lib/core/engine/command/android.js

@@ -1,16 +1,27 @@
 import intel from 'intel';
 import { Android, isAndroidConfigured } from '../../../android/index.js';
 const log = intel.getLogger('browsertime.command.android');
+/**
+ * Provides functionality to interact with an Android device through shell commands.
+ *
+ * @class
+ */
 export class AndroidCommand {
   constructor(options) {
+    /**
+     * @private
+     */
     this.options = options;
   }
 
   /**
-   * Run a shell command on your Android phone.
-   * @param {string} command The shell command to run on your phone.
-   * @returns {Promise} Promise object represents the outcome of the command or when the command has finished
-   * @throws Will throw an error Android isn't configured or something goes wrong
+   * Runs a shell command on the connected Android device.
+   * This method requires the Android device to be properly configured.
+   *
+   * @async
+   * @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.
    */
   async shell(command) {
     if (isAndroidConfigured(this.options)) {

lib/core/engine/command/cache.js

@@ -1,5 +1,11 @@
 import intel from 'intel';
 const log = intel.getLogger('browsertime.command.cache');
+/**
+ * Manage the browser cache.
+ * This class provides methods to clear the cache and cookies in different browsers.
+ *
+ * @class
+ */
 export class Cache {
   constructor(browser, browserName, extensionServer, cdp) {
     /**

lib/core/engine/command/chromeDevToolsProtocol.js

@@ -1,13 +1,33 @@
 import intel from 'intel';
 const log = intel.getLogger('browsertime.command.devtoolsprotocol');
 
-// https://chromedevtools.github.io/devtools-protocol/
+/**
+ * Manages interactions with the Chrome DevTools Protocol for Chrome and Edge browsers.
+ * Allows sending commands and setting up event listeners via the protocol.
+ * See https://chromedevtools.github.io/devtools-protocol/
+ *
+ * @class
+ */
 export class ChromeDevelopmentToolsProtocol {
   constructor(engineDelegate, browserName) {
+    /**
+     * @private
+     */
     this.engineDelegate = engineDelegate;
+    /**
+     * @private
+     */
     this.browserName = browserName;
   }
 
+  /**
+   * Sets up an event listener for a specific DevTools Protocol event.
+   *
+   * @async
+   * @param {string} event - The name of the event to listen for.
+   * @param {Function} f - The callback function to execute when the event is triggered.
+   * @throws {Error} Throws an error if the browser is not supported or if setting the listener fails.
+   */
   async on(event, f) {
     if (this.browserName === 'chrome' || this.browserName === 'edge') {
       try {
@@ -29,6 +49,15 @@ export class ChromeDevelopmentToolsProtocol {
     }
   }
 
+  /**
+   * Sends a command to the DevTools Protocol and returns the result.
+   *
+   * @async
+   * @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.
+   * @returns {Promise<Object>} The result of the command execution.
+   */
   async sendAndGet(command, arguments_) {
     if (this.browserName === 'chrome' || this.browserName === 'edge') {
       try {
@@ -51,6 +80,12 @@ export class ChromeDevelopmentToolsProtocol {
     }
   }
 
+  /**
+   * Retrieves the raw client for the DevTools Protocol.
+   *
+   * @returns {Object} The raw DevTools Protocol client.
+   * @throws {Error} Throws an error if the browser is not supported.
+   */
   getRawClient() {
     if (this.browserName === 'chrome' || this.browserName === 'edge') {
       return this.engineDelegate.getCDPClient().getRawClient();
@@ -59,6 +94,15 @@ export class ChromeDevelopmentToolsProtocol {
     }
   }
 
+  /**
+   * Sends a command to the DevTools Protocol.
+   *
+   * @async
+   * @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.
+   * @returns {Promise<void>} A promise that resolves when the command has been sent.
+   */
   async send(command, arguments_) {
     if (this.browserName === 'chrome' || this.browserName === 'edge') {
       try {

lib/core/engine/command/chromeTrace.js

@@ -4,14 +4,38 @@ import { getRenderBlocking } from '../../../chrome/webdriver/traceUtilities.js';
 import { parse } from '../../../chrome/traceCategoriesParser.js';
 import { parseCPUTrace } from '../../../chrome/parseCpuTrace.js';
 const log = intel.getLogger('browsertime.command.chrometrace');
+/**
+ * Manages Chrome trace functionality, enabling custom profiling and trace collection in Chrome.
+ *
+ * @class
+ */
 export class ChromeTrace {
   constructor(engineDelegate, index, options, result) {
+    /**
+     * @private
+     */
     this.engineDelegate = engineDelegate;
+    /**
+     * @private
+     */
     this.options = options;
+    /**
+     * @private
+     */
     this.result = result;
+    /**
+     * @private
+     */
     this.index = index;
   }
 
+  /**
+   * Starts the Chrome trace collection.
+   *
+   * @async
+   * @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.
+   */
   async start() {
     if (this.options.browser === 'chrome') {
       if (this.options.chrome.timelineRecordingType === 'custom') {
@@ -26,6 +50,13 @@ export class ChromeTrace {
     }
   }
 
+  /**
+   * Stops the Chrome trace collection, processes the collected data, and attaches it to the result object.
+   *
+   * @async
+   * @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.
+   */
   async stop() {
     if (this.options.browser === 'chrome') {
       if (this.options.chrome.timelineRecordingType === 'custom') {