[EBT][chore] Reduce APIs missing comments (#132866)

packages/analytics/client/src/schema/types.ts

@@ -40,9 +40,15 @@ export type PossibleSchemaTypes<Value> = Value extends string | Date
   : // allow any schema type from the union if typescript is unable to resolve the exact U type
     AllowedSchemaTypes;
 
+/**
+ * Schema to define a primitive value
+ */
 export interface SchemaChildValue<Value> {
+  /** The type of the value */
   type: PossibleSchemaTypes<NonNullable<Value>>;
+  /** Meta properties of the value: description and is optional */
   _meta: {
+    /** A description of the value */
     description: string; // Intentionally enforcing the descriptions here
   } & SchemaMetaOptional<Value>;
 }
@@ -55,8 +61,11 @@ export interface SchemaChildValue<Value> {
 export type SchemaValue<Value> =
   // Always allow the pass_through no matter what the value is
   | {
+      /** Type specification of a pass through object */
       type: 'pass_through';
+      /** Meta properties of the pass through: description and is optional */
       _meta: {
+        /** A description of the value */
         description: string; // Intentionally enforcing the descriptions here
       } & SchemaMetaOptional<Value>;
     }
@@ -85,7 +94,9 @@ export type SchemaMetaOptional<Value> = unknown extends Value
  * Schema meta with optional description
  */
 export interface SchemaMeta<Value> {
+  /** Meta properties of the pass through: description and is optional */
   _meta?: {
+    /** A description of the value */
     description?: string;
   } & SchemaMetaOptional<Value>;
 }
@@ -94,7 +105,9 @@ export interface SchemaMeta<Value> {
  * Schema to represent an array
  */
 export interface SchemaArray<Value, Base> extends SchemaMeta<Base> {
+  /** The type must be an array */
   type: 'array';
+  /** The schema of the items in the array is defined in the `items` property */
   items: SchemaValue<Value>;
 }
 
@@ -102,6 +115,9 @@ export interface SchemaArray<Value, Base> extends SchemaMeta<Base> {
  * Schema to represent an object
  */
 export interface SchemaObject<Value> extends SchemaMeta<Value> {
+  /**
+   * The schemas of the keys of the object are defined in the `properties` object.
+   */
   properties: {
     [Key in keyof Required<Value>]: SchemaValue<Value[Key]>;
   };

packages/analytics/shippers/elastic_v3/browser/src/browser_shipper.ts

@@ -22,8 +22,14 @@ import {
   eventsToNDJSON,
 } from '@kbn/analytics-shippers-elastic-v3-common';
 
+/**
+ * Elastic V3 shipper to use in the browser.
+ */
 export class ElasticV3BrowserShipper implements IShipper {
+  /** Shipper's unique name */
   public static shipperName = 'elastic_v3_browser';
+
+  /** Observable to emit the stats of the processed events. */
   public readonly telemetryCounter$ = new Subject<TelemetryCounter>();
 
   private readonly reportTelemetryCounters = createTelemetryCounterHelper(
@@ -38,6 +44,11 @@ export class ElasticV3BrowserShipper implements IShipper {
   private clusterUuid: string = 'UNKNOWN';
   private licenseId: string | undefined;
 
+  /**
+   * Creates a new instance of the {@link ElasticV3BrowserShipper}.
+   * @param options {@link ElasticV3ShipperOptions}
+   * @param initContext {@link AnalyticsClientInitContext}
+   */
   constructor(
     private readonly options: ElasticV3ShipperOptions,
     private readonly initContext: AnalyticsClientInitContext
@@ -49,6 +60,11 @@ export class ElasticV3BrowserShipper implements IShipper {
     });
   }
 
+  /**
+   * Uses the `cluster_uuid` and `license_id` from the context to hold them in memory for the generation of the headers
+   * used later on in the HTTP request.
+   * @param newContext The full new context to set {@link EventContext}
+   */
   public extendContext(newContext: EventContext) {
     if (newContext.cluster_uuid) {
       this.clusterUuid = newContext.cluster_uuid;
@@ -58,16 +74,28 @@ export class ElasticV3BrowserShipper implements IShipper {
     }
   }
 
+  /**
+   * When `false`, it flushes the internal queue and stops sending events.
+   * @param isOptedIn `true` for resume sending events. `false` to stop.
+   */
   public optIn(isOptedIn: boolean) {
     this.isOptedIn$.next(isOptedIn);
   }
 
+  /**
+   * Enqueues the events to be sent to in a batched approach.
+   * @param events batched events {@link Event}
+   */
   public reportEvents(events: Event[]) {
     events.forEach((event) => {
       this.internalQueue$.next(event);
     });
   }
 
+  /**
+   * Shuts down the shipper.
+   * Triggers a flush of the internal queue to attempt to send any events held in the queue.
+   */
   public shutdown() {
     this.internalQueue$.complete(); // NOTE: When completing the observable, the buffer logic does not wait and releases any buffered events.
   }

packages/analytics/shippers/elastic_v3/common/src/build_headers.ts

@@ -6,6 +6,12 @@
  * Side Public License, v 1.
  */
 
+/**
+ * Returns the headers to send to the Remote Telemetry Service.
+ * @param clusterUuid The UUID of the ES cluster.
+ * @param version The version of the ES cluster.
+ * @param licenseId The ID of the license (if available).
+ */
 export function buildHeaders(clusterUuid: string, version: string, licenseId?: string) {
   return {
     'content-type': 'application/x-ndjson',

packages/analytics/shippers/elastic_v3/common/src/build_url.ts

@@ -6,18 +6,20 @@
  * Side Public License, v 1.
  */
 
+/** The options to build the URL of the V3 API. */
+export interface BuildUrlOptions {
+  /** Whether to send it to production or staging. */
+  sendTo: 'production' | 'staging';
+  /** The name of the channel to send the data to. */
+  channelName: string;
+}
+
 /**
  * Builds the URL for the V3 API.
- * @param sendTo Whether to send it to production or staging.
- * @param channelName The name of the channel to send the data to.
+ * @param urlOptions The options to build the URL of the V3 API.
  */
-export function buildUrl({
-  sendTo,
-  channelName,
-}: {
-  sendTo: 'production' | 'staging';
-  channelName: string;
-}): string {
+export function buildUrl(urlOptions: BuildUrlOptions): string {
+  const { sendTo, channelName } = urlOptions;
   const baseUrl =
     sendTo === 'production'
       ? 'https://telemetry.elastic.co'

packages/analytics/shippers/elastic_v3/common/src/error_with_code.ts

@@ -6,7 +6,15 @@
  * Side Public License, v 1.
  */
 
+/**
+ * Custom error to report the error message with an additional error code.
+ */
 export class ErrorWithCode extends Error {
+  /**
+   * Constructor of the error.
+   * @param message The error message.
+   * @param code The code of the error.
+   */
   constructor(message: string, public readonly code: string) {
     super(message);
   }

packages/analytics/shippers/elastic_v3/common/src/events_to_ndjson.ts

@@ -8,6 +8,10 @@
 
 import type { Event } from '@kbn/analytics-client';
 
+/**
+ * Converts an array of events to a single ndjson string.
+ * @param events An array of events {@link Event}
+ */
 export function eventsToNDJSON(events: Event[]): string {
   return `${events.map((event) => JSON.stringify(event)).join('\n')}\n`;
 }

packages/analytics/shippers/elastic_v3/common/src/index.ts

@@ -8,6 +8,7 @@
 
 export { buildHeaders } from './build_headers';
 export { buildUrl } from './build_url';
+export type { BuildUrlOptions } from './build_url';
 export { ErrorWithCode } from './error_with_code';
 export { eventsToNDJSON } from './events_to_ndjson';
 export { createTelemetryCounterHelper } from './report_telemetry_counters';

packages/analytics/shippers/elastic_v3/server/src/server_shipper.ts

@@ -44,8 +44,14 @@ const HOUR = 60 * MINUTE;
 const KIB = 1024;
 const MAX_NUMBER_OF_EVENTS_IN_INTERNAL_QUEUE = 1000;
 
+/**
+ * Elastic V3 shipper to use on the server side.
+ */
 export class ElasticV3ServerShipper implements IShipper {
+  /** Shipper's unique name */
   public static shipperName = 'elastic_v3_server';
+
+  /** Observable to emit the stats of the processed events. */
   public readonly telemetryCounter$ = new Subject<TelemetryCounter>();
 
   private readonly reportTelemetryCounters = createTelemetryCounterHelper(
@@ -73,6 +79,11 @@ export class ElasticV3ServerShipper implements IShipper {
    */
   private firstTimeOffline?: number | null;
 
+  /**
+   * Creates a new instance of the {@link ElasticV3ServerShipper}.
+   * @param options {@link ElasticV3ShipperOptions}
+   * @param initContext {@link AnalyticsClientInitContext}
+   */
   constructor(
     private readonly options: ElasticV3ShipperOptions,
     private readonly initContext: AnalyticsClientInitContext
@@ -85,6 +96,11 @@ export class ElasticV3ServerShipper implements IShipper {
     this.checkConnectivity();
   }
 
+  /**
+   * Uses the `cluster_uuid` and `license_id` from the context to hold them in memory for the generation of the headers
+   * used later on in the HTTP request.
+   * @param newContext The full new context to set {@link EventContext}
+   */
   public extendContext(newContext: EventContext) {
     if (newContext.cluster_uuid) {
       this.clusterUuid = newContext.cluster_uuid;
@@ -94,6 +110,10 @@ export class ElasticV3ServerShipper implements IShipper {
     }
   }
 
+  /**
+   * When `false`, it flushes the internal queue and stops sending events.
+   * @param isOptedIn `true` for resume sending events. `false` to stop.
+   */
   public optIn(isOptedIn: boolean) {
     this.isOptedIn = isOptedIn;
 
@@ -102,6 +122,10 @@ export class ElasticV3ServerShipper implements IShipper {
     }
   }
 
+  /**
+   * Enqueues the events to be sent via the leaky bucket algorithm.
+   * @param events batched events {@link Event}
+   */
   public reportEvents(events: Event[]) {
     if (
       this.isOptedIn === false ||
@@ -125,6 +149,10 @@ export class ElasticV3ServerShipper implements IShipper {
     this.internalQueue.push(...events);
   }
 
+  /**
+   * Shuts down the shipper.
+   * Triggers a flush of the internal queue to attempt to send any events held in the queue.
+   */
   public shutdown() {
     this.shutdown$.complete();
   }

packages/analytics/shippers/fullstory/src/fullstory_shipper.ts

@@ -55,8 +55,8 @@ export class FullStoryShipper implements IShipper {
   }
 
   /**
-   * {@inheritDoc IShipper.extendContext}
-   * @param newContext {@inheritDoc IShipper.extendContext.newContext}
+   * Calls `fs.identify`, `fs.setUserVars` and `fs.setVars` depending on the fields provided in the newContext.
+   * @param newContext The full new context to set {@link EventContext}
    */
   public extendContext(newContext: EventContext): void {
     this.initContext.logger.debug(`Received context ${JSON.stringify(newContext)}`);
@@ -97,8 +97,8 @@ export class FullStoryShipper implements IShipper {
   }
 
   /**
-   * {@inheritDoc IShipper.optIn}
-   * @param isOptedIn {@inheritDoc IShipper.optIn.isOptedIn}
+   * Stops/restarts the shipping mechanism based on the value of isOptedIn
+   * @param isOptedIn `true` for resume sending events. `false` to stop.
    */
   public optIn(isOptedIn: boolean): void {
     this.initContext.logger.debug(`Setting FS to optIn ${isOptedIn}`);
@@ -116,8 +116,9 @@ export class FullStoryShipper implements IShipper {
   }
 
   /**
-   * {@inheritDoc IShipper.reportEvents}
-   * @param events {@inheritDoc IShipper.reportEvents.events}
+   * Filters the events by the eventTypesAllowlist from the config.
+   * Then it transforms the event into a FS valid format and calls `fs.event`.
+   * @param events batched events {@link Event}
    */
   public reportEvents(events: Event[]): void {
     this.initContext.logger.debug(`Reporting ${events.length} events to FS`);
@@ -129,6 +130,10 @@ export class FullStoryShipper implements IShipper {
       });
   }
 
+  /**
+   * Shuts down the shipper.
+   * It doesn't really do anything inside because this shipper doesn't hold any internal queues.
+   */
   public shutdown() {
     // No need to do anything here for now.
   }