Convert enum comments to doc comments

dlarocque · dlarocque · commit 236714b0bb71 · 2025-01-30T11:27:24.000-05:00
diff --git a/common/api-review/vertexai.api.md b/common/api-review/vertexai.api.md
@@ -28,9 +28,7 @@ export interface BaseParams {
 
 // @public
 export enum BlockReason {
-    // (undocumented)
     OTHER = "OTHER",
-    // (undocumented)
     SAFETY = "SAFETY"
 }
 
@@ -157,15 +155,10 @@ export interface FileDataPart {
 
 // @public
 export enum FinishReason {
-    // (undocumented)
     MAX_TOKENS = "MAX_TOKENS",
-    // (undocumented)
     OTHER = "OTHER",
-    // (undocumented)
     RECITATION = "RECITATION",
-    // (undocumented)
     SAFETY = "SAFETY",
-    // (undocumented)
     STOP = "STOP"
 }
 
@@ -187,11 +180,8 @@ export interface FunctionCallingConfig {
 
 // @public (undocumented)
 export enum FunctionCallingMode {
-    // (undocumented)
     ANY = "ANY",
-    // (undocumented)
     AUTO = "AUTO",
-    // (undocumented)
     NONE = "NONE"
 }
 
@@ -375,21 +365,15 @@ export interface GroundingMetadata {
 
 // @public (undocumented)
 export enum HarmBlockMethod {
-    // (undocumented)
     PROBABILITY = "PROBABILITY",
-    // (undocumented)
     SEVERITY = "SEVERITY"
 }
 
 // @public
 export enum HarmBlockThreshold {
-    // (undocumented)
     BLOCK_LOW_AND_ABOVE = "BLOCK_LOW_AND_ABOVE",
-    // (undocumented)
     BLOCK_MEDIUM_AND_ABOVE = "BLOCK_MEDIUM_AND_ABOVE",
-    // (undocumented)
     BLOCK_NONE = "BLOCK_NONE",
-    // (undocumented)
     BLOCK_ONLY_HIGH = "BLOCK_ONLY_HIGH"
 }
 
@@ -407,25 +391,17 @@ export enum HarmCategory {
 
 // @public
 export enum HarmProbability {
-    // (undocumented)
     HIGH = "HIGH",
-    // (undocumented)
     LOW = "LOW",
-    // (undocumented)
     MEDIUM = "MEDIUM",
-    // (undocumented)
     NEGLIGIBLE = "NEGLIGIBLE"
 }
 
 // @public
 export enum HarmSeverity {
-    // (undocumented)
     HARM_SEVERITY_HIGH = "HARM_SEVERITY_HIGH",
-    // (undocumented)
     HARM_SEVERITY_LOW = "HARM_SEVERITY_LOW",
-    // (undocumented)
     HARM_SEVERITY_MEDIUM = "HARM_SEVERITY_MEDIUM",
-    // (undocumented)
     HARM_SEVERITY_NEGLIGIBLE = "HARM_SEVERITY_NEGLIGIBLE"
 }
 
diff --git a/docs-devsite/vertexai.md b/docs-devsite/vertexai.md
@@ -231,8 +231,8 @@ export declare enum BlockReason
 
 |  Member | Value | Description |
 |  --- | --- | --- |
-|  OTHER | <code>&quot;OTHER&quot;</code> |  |
-|  SAFETY | <code>&quot;SAFETY&quot;</code> |  |
+|  OTHER | <code>&quot;OTHER&quot;</code> | Content was blocked, but the reason is uncategorized. |
+|  SAFETY | <code>&quot;SAFETY&quot;</code> | Content was blocked by safety settings. |
 
 ## FinishReason
 
@@ -248,11 +248,11 @@ export declare enum FinishReason
 
 |  Member | Value | Description |
 |  --- | --- | --- |
-|  MAX\_TOKENS | <code>&quot;MAX_TOKENS&quot;</code> |  |
-|  OTHER | <code>&quot;OTHER&quot;</code> |  |
-|  RECITATION | <code>&quot;RECITATION&quot;</code> |  |
-|  SAFETY | <code>&quot;SAFETY&quot;</code> |  |
-|  STOP | <code>&quot;STOP&quot;</code> |  |
+|  MAX\_TOKENS | <code>&quot;MAX_TOKENS&quot;</code> | The maximum number of tokens as specified in the request was reached. |
+|  OTHER | <code>&quot;OTHER&quot;</code> | Unknown reason. |
+|  RECITATION | <code>&quot;RECITATION&quot;</code> | The candidate content was flagged for recitation reasons. |
+|  SAFETY | <code>&quot;SAFETY&quot;</code> | The candidate content was flagged for safety reasons. |
+|  STOP | <code>&quot;STOP&quot;</code> | Natural stop point of the model or provided stop sequence. |
 
 ## FunctionCallingMode
 
@@ -267,9 +267,9 @@ export declare enum FunctionCallingMode
 
 |  Member | Value | Description |
 |  --- | --- | --- |
-|  ANY | <code>&quot;ANY&quot;</code> |  |
-|  AUTO | <code>&quot;AUTO&quot;</code> |  |
-|  NONE | <code>&quot;NONE&quot;</code> |  |
+|  ANY | <code>&quot;ANY&quot;</code> | Model is constrained to always predicting a function call only. If "allowed\_function\_names" is set, the predicted function call will be limited to any one of "allowed\_function\_names", else the predicted function call will be any one of the provided "function\_declarations". |
+|  AUTO | <code>&quot;AUTO&quot;</code> | Default model behavior, model decides to predict either a function call or a natural language response. |
+|  NONE | <code>&quot;NONE&quot;</code> | Model will not predict any function call. Model behavior is same as when not passing any function declarations. |
 
 ## HarmBlockMethod
 
@@ -284,8 +284,8 @@ export declare enum HarmBlockMethod
 
 |  Member | Value | Description |
 |  --- | --- | --- |
-|  PROBABILITY | <code>&quot;PROBABILITY&quot;</code> |  |
-|  SEVERITY | <code>&quot;SEVERITY&quot;</code> |  |
+|  PROBABILITY | <code>&quot;PROBABILITY&quot;</code> | The harm block method uses the probability score. |
+|  SEVERITY | <code>&quot;SEVERITY&quot;</code> | The harm block method uses both probability and severity scores. |
 
 ## HarmBlockThreshold
 
@@ -301,10 +301,10 @@ export declare enum HarmBlockThreshold
 
 |  Member | Value | Description |
 |  --- | --- | --- |
-|  BLOCK\_LOW\_AND\_ABOVE | <code>&quot;BLOCK_LOW_AND_ABOVE&quot;</code> |  |
-|  BLOCK\_MEDIUM\_AND\_ABOVE | <code>&quot;BLOCK_MEDIUM_AND_ABOVE&quot;</code> |  |
-|  BLOCK\_NONE | <code>&quot;BLOCK_NONE&quot;</code> |  |
-|  BLOCK\_ONLY\_HIGH | <code>&quot;BLOCK_ONLY_HIGH&quot;</code> |  |
+|  BLOCK\_LOW\_AND\_ABOVE | <code>&quot;BLOCK_LOW_AND_ABOVE&quot;</code> | Content with NEGLIGIBLE will be allowed. |
+|  BLOCK\_MEDIUM\_AND\_ABOVE | <code>&quot;BLOCK_MEDIUM_AND_ABOVE&quot;</code> | Content with NEGLIGIBLE and LOW will be allowed. |
+|  BLOCK\_NONE | <code>&quot;BLOCK_NONE&quot;</code> | All content will be allowed. |
+|  BLOCK\_ONLY\_HIGH | <code>&quot;BLOCK_ONLY_HIGH&quot;</code> | Content with NEGLIGIBLE, LOW, and MEDIUM will be allowed. |
 
 ## HarmCategory
 
@@ -339,10 +339,10 @@ export declare enum HarmProbability
 
 |  Member | Value | Description |
 |  --- | --- | --- |
-|  HIGH | <code>&quot;HIGH&quot;</code> |  |
-|  LOW | <code>&quot;LOW&quot;</code> |  |
-|  MEDIUM | <code>&quot;MEDIUM&quot;</code> |  |
-|  NEGLIGIBLE | <code>&quot;NEGLIGIBLE&quot;</code> |  |
+|  HIGH | <code>&quot;HIGH&quot;</code> | Content has a high chance of being unsafe. |
+|  LOW | <code>&quot;LOW&quot;</code> | Content has a low chance of being unsafe. |
+|  MEDIUM | <code>&quot;MEDIUM&quot;</code> | Content has a medium chance of being unsafe. |
+|  NEGLIGIBLE | <code>&quot;NEGLIGIBLE&quot;</code> | Content has a negligible chance of being unsafe. |
 
 ## HarmSeverity
 
@@ -358,10 +358,10 @@ export declare enum HarmSeverity
 
 |  Member | Value | Description |
 |  --- | --- | --- |
-|  HARM\_SEVERITY\_HIGH | <code>&quot;HARM_SEVERITY_HIGH&quot;</code> |  |
-|  HARM\_SEVERITY\_LOW | <code>&quot;HARM_SEVERITY_LOW&quot;</code> |  |
-|  HARM\_SEVERITY\_MEDIUM | <code>&quot;HARM_SEVERITY_MEDIUM&quot;</code> |  |
-|  HARM\_SEVERITY\_NEGLIGIBLE | <code>&quot;HARM_SEVERITY_NEGLIGIBLE&quot;</code> |  |
+|  HARM\_SEVERITY\_HIGH | <code>&quot;HARM_SEVERITY_HIGH&quot;</code> | High level of harm severity. |
+|  HARM\_SEVERITY\_LOW | <code>&quot;HARM_SEVERITY_LOW&quot;</code> | Low level of harm severity. |
+|  HARM\_SEVERITY\_MEDIUM | <code>&quot;HARM_SEVERITY_MEDIUM&quot;</code> | Medium level of harm severity. |
+|  HARM\_SEVERITY\_NEGLIGIBLE | <code>&quot;HARM_SEVERITY_NEGLIGIBLE&quot;</code> | Negligible level of harm severity. |
 
 ## SchemaType
 
diff --git a/packages/vertexai/src/types/enums.ts b/packages/vertexai/src/types/enums.ts
@@ -43,23 +43,35 @@ export enum HarmCategory {
  * @public
  */
 export enum HarmBlockThreshold {
-  // Content with NEGLIGIBLE will be allowed.
+  /**
+   * Content with NEGLIGIBLE will be allowed.
+   */
   BLOCK_LOW_AND_ABOVE = 'BLOCK_LOW_AND_ABOVE',
-  // Content with NEGLIGIBLE and LOW will be allowed.
+  /**
+   * Content with NEGLIGIBLE and LOW will be allowed.
+   */
   BLOCK_MEDIUM_AND_ABOVE = 'BLOCK_MEDIUM_AND_ABOVE',
-  // Content with NEGLIGIBLE, LOW, and MEDIUM will be allowed.
+  /**
+   * Content with NEGLIGIBLE, LOW, and MEDIUM will be allowed.
+   */
   BLOCK_ONLY_HIGH = 'BLOCK_ONLY_HIGH',
-  // All content will be allowed.
+  /**
+   * All content will be allowed.
+   */
   BLOCK_NONE = 'BLOCK_NONE'
 }
 
 /**
  * @public
  */
 export enum HarmBlockMethod {
-  // The harm block method uses both probability and severity scores.
+  /**
+   *  The harm block method uses both probability and severity scores.
+   */
   SEVERITY = 'SEVERITY',
-  // The harm block method uses the probability score.
+  /**
+   * The harm block method uses the probability score.
+   */
   PROBABILITY = 'PROBABILITY'
 }
 
@@ -68,13 +80,21 @@ export enum HarmBlockMethod {
  * @public
  */
 export enum HarmProbability {
-  // Content has a negligible chance of being unsafe.
+  /**
+   * Content has a negligible chance of being unsafe.
+   */
   NEGLIGIBLE = 'NEGLIGIBLE',
-  // Content has a low chance of being unsafe.
+  /**
+   * Content has a low chance of being unsafe.
+   */
   LOW = 'LOW',
-  // Content has a medium chance of being unsafe.
+  /**
+   * Content has a medium chance of being unsafe.
+   */
   MEDIUM = 'MEDIUM',
-  // Content has a high chance of being unsafe.
+  /**
+   * Content has a high chance of being unsafe.
+   */
   HIGH = 'HIGH'
 }
 
@@ -83,13 +103,21 @@ export enum HarmProbability {
  * @public
  */
 export enum HarmSeverity {
-  // Negligible level of harm severity.
+  /**
+   * Negligible level of harm severity.
+   */
   HARM_SEVERITY_NEGLIGIBLE = 'HARM_SEVERITY_NEGLIGIBLE',
-  // Low level of harm severity.
+  /**
+   * Low level of harm severity.
+   */
   HARM_SEVERITY_LOW = 'HARM_SEVERITY_LOW',
-  // Medium level of harm severity.
+  /**
+   * Medium level of harm severity.
+   */
   HARM_SEVERITY_MEDIUM = 'HARM_SEVERITY_MEDIUM',
-  // High level of harm severity.
+  /**
+   * High level of harm severity.
+   */
   HARM_SEVERITY_HIGH = 'HARM_SEVERITY_HIGH'
 }
 
@@ -98,9 +126,13 @@ export enum HarmSeverity {
  * @public
  */
 export enum BlockReason {
-  // Content was blocked by safety settings.
+  /**
+   * Content was blocked by safety settings.
+   */
   SAFETY = 'SAFETY',
-  // Content was blocked, but the reason is uncategorized.
+  /**
+   * Content was blocked, but the reason is uncategorized.
+   */
   OTHER = 'OTHER'
 }
 
@@ -109,31 +141,47 @@ export enum BlockReason {
  * @public
  */
 export enum FinishReason {
-  // Natural stop point of the model or provided stop sequence.
+  /**
+   * Natural stop point of the model or provided stop sequence.
+   */
   STOP = 'STOP',
-  // The maximum number of tokens as specified in the request was reached.
+  /**
+   * The maximum number of tokens as specified in the request was reached.
+   */
   MAX_TOKENS = 'MAX_TOKENS',
-  // The candidate content was flagged for safety reasons.
+  /**
+   * The candidate content was flagged for safety reasons.
+   */
   SAFETY = 'SAFETY',
-  // The candidate content was flagged for recitation reasons.
+  /**
+   * The candidate content was flagged for recitation reasons.
+   */
   RECITATION = 'RECITATION',
-  // Unknown reason.
+  /**
+   * Unknown reason.
+   */
   OTHER = 'OTHER'
 }
 
 /**
  * @public
  */
 export enum FunctionCallingMode {
-  // Default model behavior, model decides to predict either a function call
-  // or a natural language response.
+  /**
+   * Default model behavior, model decides to predict either a function call
+   * or a natural language response.
+   */
   AUTO = 'AUTO',
-  // Model is constrained to always predicting a function call only.
-  // If "allowed_function_names" is set, the predicted function call will be
-  // limited to any one of "allowed_function_names", else the predicted
-  // function call will be any one of the provided "function_declarations".
+  /**
+   * Model is constrained to always predicting a function call only.
+   * If "allowed_function_names" is set, the predicted function call will be
+   * limited to any one of "allowed_function_names", else the predicted
+   * function call will be any one of the provided "function_declarations".
+   */
   ANY = 'ANY',
-  // Model will not predict any function call. Model behavior is same as when
-  // not passing any function declarations.
+  /**
+   * Model will not predict any function call. Model behavior is same as when
+   * not passing any function declarations.
+   */
   NONE = 'NONE'
 }
