[ML] Fix JSDoc for @kbn/ml-agg-utils. (elastic#167734)

Fixes JSDoc annotations for package `@kbn/ml-agg-utils`.

x-pack/packages/ml/agg_utils/src/build_sampler_aggregation.ts

@@ -11,6 +11,11 @@ import * as estypes from '@elastic/elasticsearch/lib/api/typesWithBodyKey';
  * Wraps the supplied aggregations in a sampler aggregation.
  * A supplied samplerShardSize (the shard_size parameter of the sampler aggregation)
  * of less than 1 indicates no sampling, and the aggs are returned as-is.
+ *
+ * @param aggs - The aggregations to be wrapped in the sampler aggregation.
+ * @param shardSize - The shard size parameter for the sampler aggregation.
+ *                    A value less than 1 indicates no sampling.
+ * @returns The wrapped aggregations.
  */
 export function buildSamplerAggregation(
   aggs: any,

x-pack/packages/ml/agg_utils/src/fetch_agg_intervals.ts

@@ -23,6 +23,17 @@ const MAX_CHART_COLUMNS = 20;
 
 /**
  * Returns aggregation intervals for the supplied document fields.
+ *
+ * @param client - The Elasticsearch client.
+ * @param indexPattern - The index pattern to search.
+ * @param query - The query to filter documents.
+ * @param fields - An array of field definitions for which aggregation intervals are requested.
+ * @param samplerShardSize - The shard size parameter for sampling aggregations. A value less than 1 indicates no sampling.
+ * @param runtimeMappings - Optional runtime mappings to apply.
+ * @param abortSignal - Optional AbortSignal for canceling the request.
+ * @param randomSamplerProbability - Optional probability value for random sampling.
+ * @param randomSamplerSeed - Optional seed value for random sampling.
+ * @returns A promise that resolves to a map of aggregation intervals for the specified fields.
  */
 export const fetchAggIntervals = async (
   client: ElasticsearchClient,

x-pack/packages/ml/agg_utils/src/fetch_histograms_for_fields.ts

@@ -41,27 +41,65 @@ interface AggTerms {
   };
 }
 
+/**
+ * Represents an item in numeric data.
+ * @interface
+ */
 interface NumericDataItem {
+  /**
+   * The numeric key.
+   */
   key: number;
+
+  /**
+   * An optional string representation of the key.
+   */
   key_as_string?: string;
+
+  /**
+   * The document count associated with the key.
+   */
   doc_count: number;
 }
 
 /**
- * Interface to describe the data structure returned for numeric based charts.
+ * Interface describing the data structure returned for numeric-based charts.
+ * @interface
  */
 export interface NumericChartData {
+  /**
+   * An array of data points, each represented by a NumericDataItem.
+   */
   data: NumericDataItem[];
+
+  /**
+   * The identifier for the data set.
+   */
   id: string;
+
+  /**
+   * The interval value for the data.
+   */
   interval: number;
+
+  /**
+   * An array of statistics values, typically [min, max].
+   */
   stats: [number, number];
+
+  /**
+   * The type of chart, which is 'numeric'.
+   */
   type: 'numeric';
 }
 
 /**
  * Numeric based histogram field interface, limited to `date` and `number`.
  */
 export interface NumericHistogramField extends HistogramField {
+  /**
+   * The type of the numeric histogram field.
+   */
   type: KBN_FIELD_TYPES.DATE | KBN_FIELD_TYPES.NUMBER;
 }
 type NumericHistogramFieldWithColumnStats = NumericHistogramField & NumericColumnStats;
@@ -139,6 +177,7 @@ export type FieldsForHistograms = Array<
  * @param fields the fields the histograms should be generated for
  * @param samplerShardSize shard_size parameter of the sampler aggregation
  * @param runtimeMappings optional runtime mappings
+ * @param abortSignal optional abort signal
  * @param randomSamplerProbability optional random sampler probability
  * @param randomSamplerSeed optional random sampler seed
  * @returns an array of histogram data for each supplied field

x-pack/packages/ml/agg_utils/src/get_sampler_aggregations_response_path.ts

@@ -5,10 +5,14 @@
  * 2.0.
  */
 
-// Returns the path of aggregations in the elasticsearch response, as an array,
-// depending on whether sampling is being used.
-// A supplied samplerShardSize (the shard_size parameter of the sampler aggregation)
-// of less than 1 indicates no sampling, and an empty array is returned.
+/**
+ * Returns the path of aggregations in the Elasticsearch response as an array,
+ * depending on whether sampling is being used.
+ *
+ * @param samplerShardSize - The shard size parameter of the sampler aggregation.
+ *                           A value less than 1 indicates no sampling.
+ * @returns An array representing the path of aggregations in the response.
+ */
 export function getSamplerAggregationsResponsePath(samplerShardSize: number): string[] {
   return samplerShardSize > 0 ? ['sample'] : [];
 }

x-pack/packages/ml/agg_utils/src/types.ts

@@ -7,39 +7,62 @@
 
 import { KBN_FIELD_TYPES } from '@kbn/field-types';
 
+/**
+ * Represents a field-based cardinality aggregation configuration.
+ * @interface
+ */
 interface FieldAggCardinality {
+  /** The field on which the cardinality aggregation is applied. */
   field: string;
+
+  /** Optional property percent. */
   percent?: any;
 }
 
+/**
+ * Represents a script-based cardinality aggregation configuration.
+ * @interface
+ */
 interface ScriptAggCardinality {
+  /** The script used for the cardinality aggregation. */
   script: any;
 }
 
 /**
  * Interface for cardinality aggregation.
+ * @interface
  */
 export interface AggCardinality {
+  /** The cardinality aggregation configuration */
   cardinality: FieldAggCardinality | ScriptAggCardinality;
 }
 
 /**
  * Field/value pair definition.
  */
 export interface FieldValuePair {
+  /** The field name. */
   fieldName: string;
-  // For dynamic fieldValues we only identify fields as `string`,
-  // but for example `http.response.status_code` which is part of
-  // of the list of predefined field candidates is of type long/number.
+  /**
+   * For dynamic fieldValues we only identify fields as `string`,
+   * but for example `http.response.status_code` which is part of
+   * of the list of predefined field candidates is of type long/number
+   */
   fieldValue: string | number;
 }
 
 /**
- * Interface to describe attributes used for histograms.
+ * Interface describing attributes used for numeric histograms.
+ * @interface
  */
 export interface NumericColumnStats {
+  /** The interval value for the histogram. */
   interval: number;
+
+  /** The minimum value in the histogram. */
   min: number;
+
+  /** The maximum value in the histogram. */
   max: number;
 }
 
@@ -49,69 +72,130 @@ export interface NumericColumnStats {
 export type NumericColumnStatsMap = Record<string, NumericColumnStats>;
 
 /**
- * Parameters to identify which histogram data needs to be generated for a field.
+ * Represents parameters used to identify which histogram data needs to be generated for a field.
+ * @interface
  */
 export interface HistogramField {
+  /**
+   * The name of the field for which histogram data is generated.
+   */
   fieldName: string;
+
+  /**
+   * The type of the field, using Kibana field types.
+   */
   type: KBN_FIELD_TYPES;
 }
 
 /**
- * Significant term meta data for a field/value pair.
- * Note this is used as a custom type within Log Rate Analysis
- * for a p-value based variant, not a generic significant terms
- * aggregation type.
+ * Represents significant term metadata for a field/value pair.
+ * This interface is used as a custom type within Log Rate Analysis
+ * for a p-value based variant, not related to the generic
+ * significant terms aggregation type.
+ *
+ * @interface
+ * @extends FieldValuePair
  */
 export interface SignificantTerm extends FieldValuePair {
+  /** The document count for the significant term. */
   doc_count: number;
+
+  /** The background count for the significant term. */
   bg_count: number;
+
+  /** The total document count for all terms. */
   total_doc_count: number;
+
+  /** The total background count for all terms. */
   total_bg_count: number;
+
+  /** The score associated with the significant term. */
   score: number;
+
+  /** The p-value for the significant term, or null if not available. */
   pValue: number | null;
+
+  /** The normalized score for the significant term. */
   normalizedScore: number;
+
+  /** An optional histogram of significant term items. */
   histogram?: SignificantTermHistogramItem[];
+
+  /** Indicates if the significant term is unique within a group. */
   unique?: boolean;
 }
 
 /**
- * Significant term histogram data item.
+ * Represents a data item in a significant term histogram.
+ * @interface
  */
 export interface SignificantTermHistogramItem {
+  /** The document count for this item in the overall context. */
   doc_count_overall: number;
+
+  /** The document count for this item in the significant term context. */
   doc_count_significant_term: number;
+
+  /** The numeric key associated with this item. */
   key: number;
+
+  /** The string representation of the key. */
   key_as_string: string;
 }
 
 /**
- * Histogram data for a field/value pair.
+ * Represents histogram data for a field/value pair.
+ * @interface
  */
 export interface SignificantTermHistogram extends FieldValuePair {
+  /** An array of significant term histogram items. */
   histogram: SignificantTermHistogramItem[];
 }
 
 /**
- * Histogram data for a group of field/value pairs.
+ * Represents histogram data for a group of field/value pairs.
+ * @interface
  */
 export interface SignificantTermGroupHistogram {
+  /** The identifier for the group. */
   id: string;
+
+  /** An array of significant term histogram items. */
   histogram: SignificantTermHistogramItem[];
 }
 
+/**
+ * Represents an item in a significant term group.
+ * @interface
+ */
 export interface SignificantTermGroupItem extends FieldValuePair {
+  /** The document count associated with this item. */
   docCount: number;
+
+  /** The p-value for this item, or null if not available. */
   pValue: number | null;
+
+  /** An optional number of duplicates. */
   duplicate?: number;
 }
 
 /**
- * Tree leaves
+ * Represents a significant term group.
+ * @interface
  */
 export interface SignificantTermGroup {
+  /** The identifier for the item. */
   id: string;
+
+  /** An array of significant term group items. */
   group: SignificantTermGroupItem[];
+
+  /** The document count associated with this item. */
   docCount: number;
+
+  /** The p-value for this item, or null if not available. */
   pValue: number | null;
+
+  /** An optional array of significant term histogram items. */
   histogram?: SignificantTermHistogramItem[];
 }

x-pack/packages/ml/agg_utils/src/validate_number.ts

@@ -8,20 +8,50 @@
 import { memoize } from 'lodash';
 import { isPopulatedObject } from '@kbn/ml-is-populated-object';
 
+/**
+ * Represents the result of number validation.
+ * @interface
+ */
 export interface NumberValidationResult {
+  /** The minimum allowed value. */
   min: boolean;
+
+  /** The maximum allowed value. */
   max: boolean;
+
+  /** Boolean flag to allow integer values only. */
   integerOnly: boolean;
 }
 
 /**
- * Validate if a number is greater than a specified minimum & lesser than specified maximum
+ * An interface describing conditions for validating numbers.
+ * @interface
  */
-export function numberValidator(conditions?: {
+interface NumberValidatorConditions {
+  /**
+   * The minimum value for validation.
+   */
   min?: number;
+
+  /**
+   * The maximum value for validation.
+   */
   max?: number;
+
+  /**
+   * Indicates whether only integer values are valid.
+   */
   integerOnly?: boolean;
-}) {
+}
+
+/**
+ * Validate if a number is within specified minimum and maximum bounds.
+ *
+ * @param conditions - An optional object containing validation conditions.
+ * @returns validation results.
+ * @throws {Error} If the provided conditions are invalid (min is greater than max).
+ */
+export function numberValidator(conditions?: NumberValidatorConditions) {
   if (
     conditions?.min !== undefined &&
     conditions.max !== undefined &&