update javadocs (#6848)

Co-authored-by: Rodrigo Lazo <rlazo@users.noreply.github.com>
Co-authored-by: Daymon <17409137+daymxn@users.noreply.github.com>

Author: 3 people

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/type/LiveContentResponse.kt

@@ -16,26 +16,58 @@
 
 package com.google.firebase.vertexai.type
 
-/* Represents the response from the server. */
+/**
+ * Represents the response from the model for live content updates.
+ *
+ * This class encapsulates the content data, the status of the response, and any function calls
+ * included in the response.
+ */
 @PublicPreviewAPI
 public class LiveContentResponse
 internal constructor(
+
+  /** The main content data of the response. This can be `null` if there is no content. */
   public val data: Content?,
+
+  /**
+   * The status of the live content response. Indicates whether the response is normal, was
+   * interrupted, or signifies the completion of a turn.
+   */
   public val status: Status,
+
+  /**
+   * A list of [FunctionCallPart] included in the response, if any.
+   *
+   * This list can be null or empty if no function calls are present.
+   */
   public val functionCalls: List<FunctionCallPart>?
 ) {
+
   /**
    * Convenience field representing all the text parts in the response as a single string, if they
    * exists.
    */
   public val text: String? =
     data?.parts?.filterIsInstance<TextPart>()?.joinToString(" ") { it.text }
 
+  /** Represents the status of a [LiveContentResponse], within a single interaction. */
   @JvmInline
   public value class Status private constructor(private val value: Int) {
     public companion object {
+      /** The server is actively sending data for the current interaction. */
       public val NORMAL: Status = Status(0)
+      /**
+       * The server was interrupted while generating data.
+       *
+       * An interruption occurs when the client sends a message while the server is [actively]
+       * [NORMAL] sending data.
+       */
       public val INTERRUPTED: Status = Status(1)
+      /**
+       * The model has finished sending data in the current interaction.
+       *
+       * Can be set alongside content, signifying that the content is the last in the turn.
+       */
       public val TURN_COMPLETE: Status = Status(2)
     }
   }

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/type/LiveSession.kt

@@ -20,6 +20,7 @@ import android.media.AudioFormat
 import android.media.AudioTrack
 import android.util.Log
 import com.google.firebase.annotations.concurrent.Background
+import com.google.firebase.vertexai.LiveGenerativeModel
 import io.ktor.client.plugins.websocket.ClientWebSocketSession
 import io.ktor.websocket.Frame
 import io.ktor.websocket.close
@@ -232,8 +233,14 @@ internal constructor(
   }
 
   /**
-   * Stops receiving from the server. If this function is called during an ongoing audio
-   * conversation, the server's response will not be received, and no audio will be played.
+   * Stops receiving from the model.
+   *
+   * If this function is called during an ongoing audio conversation, the model's response will not
+   * be received, and no audio will be played; the live session object will no longer receive data
+   * from the server.
+   *
+   * To resume receiving data, you must either handle it directly using [receive], or indirectly by
+   * using [startAudioConversation].
    */
   public fun stopReceiving() {
     if (!startedReceiving) {
@@ -355,7 +362,12 @@ internal constructor(
     send(Content.Builder().text(text).build())
   }
 
-  /** Closes the client session. */
+  /**
+   * Closes the client session.
+   *
+   * After this is called, the session object becomes unusable. To interact with the server again,
+   * you must create a new session using [LiveGenerativeModel].
+   */
   public suspend fun close() {
     session?.close()
   }

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/type/ResponseModality.kt

@@ -21,7 +21,7 @@ import kotlinx.serialization.KSerializer
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
-/** Modality for bidirectional streaming. */
+/** Represents the type of content present in a response (e.g., text, image, audio). */
 @PublicPreviewAPI
 public class ResponseModality private constructor(public val ordinal: Int) {
 
@@ -54,13 +54,13 @@ public class ResponseModality private constructor(public val ordinal: Int) {
     /** Unspecified modality. */
     @JvmField public val UNSPECIFIED: ResponseModality = ResponseModality(0)
 
-    /** Plain text. */
+    /** Represents a plain text response modality. */
     @JvmField public val TEXT: ResponseModality = ResponseModality(1)
 
-    /** Image. */
+    /** Represents an image response modality. */
     @JvmField public val IMAGE: ResponseModality = ResponseModality(2)
 
-    /** Audio. */
+    /** Represents an audio response modality. */
     @JvmField public val AUDIO: ResponseModality = ResponseModality(4)
   }
 }

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/type/SpeechConfig.kt

@@ -21,7 +21,10 @@ import kotlinx.serialization.Serializable
 
 /** Speech configuration class for setting up the voice of the server's response. */
 @PublicPreviewAPI
-public class SpeechConfig(public val voice: Voices) {
+public class SpeechConfig(
+  /** The voice to be used for the server's speech response. */
+  public val voice: Voices
+) {
 
   @Serializable
   internal data class Internal(@SerialName("voice_config") val voiceConfig: VoiceConfigInternal) {

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/type/Voices.kt

@@ -53,17 +53,26 @@ public class Voices private constructor(public val ordinal: Int) {
   }
 
   public companion object {
-    /** Unspecified modality. */
+    /**
+     * Unspecified voice.
+     *
+     * Will use the default voice of the model.
+     */
     @JvmField public val UNSPECIFIED: Voices = Voices(0)
 
+    /** Represents the Charon voice. */
     @JvmField public val CHARON: Voices = Voices(1)
 
+    /** Represents the Aoede voice. */
     @JvmField public val AOEDE: Voices = Voices(2)
 
+    /** Represents the Fenrir voice. */
     @JvmField public val FENRIR: Voices = Voices(3)
 
+    /** Represents the Kore voice. */
     @JvmField public val KORE: Voices = Voices(4)
 
+    /** Represents the Puck voice. */
     @JvmField public val PUCK: Voices = Voices(5)
   }
 }