Convert enum comments to JSDoc comments (#8742)

Author: dlarocque

common/api-review/vertexai.api.md

@@ -29,10 +29,8 @@ export interface BaseParams {
 // @public
 export enum BlockReason {
     BLOCKLIST = "BLOCKLIST",
-    // (undocumented)
     OTHER = "OTHER",
     PROHIBITED_CONTENT = "PROHIBITED_CONTENT",
-    // (undocumented)
     SAFETY = "SAFETY"
 }
 
@@ -162,17 +160,12 @@ export interface FileDataPart {
 export enum FinishReason {
     BLOCKLIST = "BLOCKLIST",
     MALFORMED_FUNCTION_CALL = "MALFORMED_FUNCTION_CALL",
-    // (undocumented)
     MAX_TOKENS = "MAX_TOKENS",
-    // (undocumented)
     OTHER = "OTHER",
     PROHIBITED_CONTENT = "PROHIBITED_CONTENT",
-    // (undocumented)
     RECITATION = "RECITATION",
-    // (undocumented)
     SAFETY = "SAFETY",
     SPII = "SPII",
-    // (undocumented)
     STOP = "STOP"
 }
 
@@ -194,11 +187,8 @@ export interface FunctionCallingConfig {
 
 // @public (undocumented)
 export enum FunctionCallingMode {
-    // (undocumented)
     ANY = "ANY",
-    // (undocumented)
     AUTO = "AUTO",
-    // (undocumented)
     NONE = "NONE"
 }
 
@@ -383,21 +373,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"
 }
 
@@ -415,25 +399,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"
 }
 

docs-devsite/vertexai.md

@@ -278,9 +278,9 @@ export declare enum BlockReason
 |  Member | Value | Description |
 |  --- | --- | --- |
 |  BLOCKLIST | <code>&quot;BLOCKLIST&quot;</code> | Content was blocked because it contained terms from the terminology blocklist. |
-|  OTHER | <code>&quot;OTHER&quot;</code> |  |
+|  OTHER | <code>&quot;OTHER&quot;</code> | Content was blocked, but the reason is uncategorized. |
 |  PROHIBITED\_CONTENT | <code>&quot;PROHIBITED_CONTENT&quot;</code> | Content was blocked due to prohibited content. |
-|  SAFETY | <code>&quot;SAFETY&quot;</code> |  |
+|  SAFETY | <code>&quot;SAFETY&quot;</code> | Content was blocked by safety settings. |
 
 ## FinishReason
 
@@ -298,13 +298,13 @@ export declare enum FinishReason
 |  --- | --- | --- |
 |  BLOCKLIST | <code>&quot;BLOCKLIST&quot;</code> | The candidate content contained forbidden terms. |
 |  MALFORMED\_FUNCTION\_CALL | <code>&quot;MALFORMED_FUNCTION_CALL&quot;</code> | The function call generated by the model was invalid. |
-|  MAX\_TOKENS | <code>&quot;MAX_TOKENS&quot;</code> |  |
-|  OTHER | <code>&quot;OTHER&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. |
 |  PROHIBITED\_CONTENT | <code>&quot;PROHIBITED_CONTENT&quot;</code> | The candidate content potentially contained prohibited content. |
-|  RECITATION | <code>&quot;RECITATION&quot;</code> |  |
-|  SAFETY | <code>&quot;SAFETY&quot;</code> |  |
+|  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. |
 |  SPII | <code>&quot;SPII&quot;</code> | The candidate content potentially contained Sensitive Personally Identifiable Information (SPII). |
-|  STOP | <code>&quot;STOP&quot;</code> |  |
+|  STOP | <code>&quot;STOP&quot;</code> | Natural stop point of the model or provided stop sequence. |
 
 ## FunctionCallingMode
 
@@ -319,9 +319,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 <code>allowed_function_names</code> is set, the predicted function call will be limited to any one of <code>allowed_function_names</code>, else the predicted function call will be any one of the provided <code>function_declarations</code>. |
+|  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
 
@@ -336,8 +336,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
 
@@ -353,10 +353,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 <code>NEGLIGIBLE</code> will be allowed. |
+|  BLOCK\_MEDIUM\_AND\_ABOVE | <code>&quot;BLOCK_MEDIUM_AND_ABOVE&quot;</code> | Content with <code>NEGLIGIBLE</code> and <code>LOW</code> 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 <code>NEGLIGIBLE</code>, <code>LOW</code>, and <code>MEDIUM</code> will be allowed. |
 
 ## HarmCategory
 
@@ -391,10 +391,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
 
@@ -410,10 +410,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. |
 
 ## ImagenAspectRatio
 

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',
   /**
    * Content was blocked because it contained terms from the terminology blocklist.
@@ -117,15 +149,25 @@ 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',
   /**
    * The candidate content contained forbidden terms.
@@ -149,16 +191,22 @@ export enum FinishReason {
  * @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'
 }