[ML] Add comments to anomaly detection types and constants in public …

…API (#123813)

* [ML] Add comments to anomaly detection types and constants in public API

* [ML] Clarify comment for job groups

* [ML] More edits to summary_job docs

Co-authored-by: Kibana Machine <[email protected]>

x-pack/plugins/ml/common/constants/anomalies.ts

@@ -5,29 +5,106 @@
  * 2.0.
  */
 
+/**
+ * Labels displayed in the ML UI to indicate the severity of the anomaly according
+ * to the normalized anomaly score.
+ */
 export enum ANOMALY_SEVERITY {
+  /**
+   * Anomalies are displayed as critical severity when the score is greater than or equal to 75.
+   */
   CRITICAL = 'critical',
+
+  /**
+   * Anomalies are displayed as major severity when the score is greater than or equal to 50 and less than 75.
+   */
   MAJOR = 'major',
+
+  /**
+   * Anomalies are displayed as minor severity when the score is greater than or equal to 25 and less than 50.
+   */
   MINOR = 'minor',
+
+  /**
+   * Anomalies are displayed as warning severity when the score is greater than or equal to 3 and less than 25.
+   * Note in some parts of the UI, warning severity is used when the score is greater than or equal to 0.
+   */
   WARNING = 'warning',
+
+  /**
+   * Anomalies are displayed as low severity in some parts of the ML UI when the score is greater than or equal to 0 and less than 3.
+   */
   LOW = 'low',
+
+  /**
+   * Anomalies are displayed as unknown severity if the anomaly score is not known.
+   */
   UNKNOWN = 'unknown',
 }
 
+/**
+ * Anomaly score numeric thresholds to indicate the severity of the anomaly.
+ */
 export enum ANOMALY_THRESHOLD {
+  /**
+   * Threshold at which anomalies are labelled in the UI as critical.
+   */
   CRITICAL = 75,
+
+  /**
+   * Threshold at which anomalies are labelled in the UI as major.
+   */
   MAJOR = 50,
+
+  /**
+   * Threshold at which anomalies are labelled in the UI as minor.
+   */
   MINOR = 25,
+
+  /**
+   * Threshold at which anomalies are labelled in the UI as warning.
+   */
   WARNING = 3,
+
+  /**
+   * Threshold at which anomalies are labelled in the UI as low.
+   */
   LOW = 0,
 }
 
+/**
+ * RGB hex codes used to indicate the severity of an anomaly according to its anomaly score.
+ */
 export const SEVERITY_COLORS = {
+  /**
+   * Color used in the UI to indicate a critical anomaly, with a score greater than or equal to 75.
+   */
   CRITICAL: '#fe5050',
+
+  /**
+   * Color used in the UI to indicate a major anomaly, with a score greater than or equal to 50 and less than 75 .
+   */
   MAJOR: '#fba740',
+
+  /**
+   * Color used in the UI to indicate a minor anomaly, with a score greater than or equal to 25 and less than 50.
+   */
   MINOR: '#fdec25',
+
+  /**
+   * Color used in the UI to indicate a warning anomaly, with a score greater than or equal to 3 and less than 25.
+   * Note in some parts of the UI, warning severity is used when the score is greater than or equal to 0.
+   */
   WARNING: '#8bc8fb',
+
+  /**
+   * Color used in some parts of the UI to indicate a low severity anomaly, with a score greater than or equal to 0 and less than 3.
+   */
   LOW: '#d2e9f7',
+
+  /**
+   * Color used in the UI to indicate an anomaly for which the score is unknown.
+   */
   BLANK: '#ffffff',
 };
 

x-pack/plugins/ml/common/constants/states.ts

@@ -5,6 +5,9 @@
  * 2.0.
  */
 
+/**
+ * The status of the datafeed.
+ */
 export enum DATAFEED_STATE {
   STARTED = 'started',
   STARTING = 'starting',
@@ -13,13 +16,19 @@ export enum DATAFEED_STATE {
   DELETED = 'deleted',
 }
 
+/**
+ * The status of the anomaly detection job forecast.
+ */
 export enum FORECAST_REQUEST_STATE {
   FAILED = 'failed',
   FINISHED = 'finished',
   SCHEDULED = 'scheduled',
   STARTED = 'started',
 }
 
+/**
+ * The status of the anomaly detection job.
+ */
 export enum JOB_STATE {
   CLOSED = 'closed',
   CLOSING = 'closing',