Add documentation to imagen (#6616)

Co-authored-by: David Motsonashvili <davidmotson@google.com>
Co-authored-by: rachelsaunders <52258509+rachelsaunders@users.noreply.github.com>

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/FirebaseVertexAI.kt

@@ -81,6 +81,15 @@ internal constructor(
     )
   }
 
+  /**
+   * Instantiates a new [ImagenModel] given the provided parameters.
+   *
+   * @param modelName The name of the model to use, for example `"imagen-3.0-generate-001"`.
+   * @param generationConfig The configuration parameters to use for image generation.
+   * @param safetySettings The safety bounds the model will abide by during image generation.
+   * @param requestOptions Configuration options for sending requests to the backend.
+   * @return The initialized [ImagenModel] instance.
+   */
   @JvmOverloads
   public fun imagenModel(
     modelName: String,

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/ImagenModel.kt

@@ -1,3 +1,19 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package com.google.firebase.vertexai
 
 import com.google.firebase.appcheck.interop.InteropAppCheckTokenProvider
@@ -20,13 +36,18 @@ import com.google.firebase.vertexai.type.ImagenInlineImage
 import com.google.firebase.vertexai.type.ImagenSafetySettings
 import com.google.firebase.vertexai.type.RequestOptions
 
+/**
+ * Represents a generative model (like Imagen), capable of generating images based on various input
+ * types.
+ */
 public class ImagenModel
 internal constructor(
   private val modelName: String,
   private val generationConfig: ImagenGenerationConfig? = null,
   private val safetySettings: ImagenSafetySettings? = null,
   private val controller: APIController,
 ) {
+  @JvmOverloads
   internal constructor(
     modelName: String,
     apiKey: String,
@@ -48,8 +69,14 @@ internal constructor(
     ),
   )
 
+  /**
+   * Generates an image, returning the result directly to the caller.
+   *
+   * @param prompt The input(s) given to the model as a prompt.
+   */
   public suspend fun generateImages(prompt: String): ImagenGenerationResponse<ImagenInlineImage> =
     try {
+      controller.generateImage(constructRequest(prompt, null, generationConfig)).toPublicInline()
       controller
         .generateImage(constructRequest(prompt, null, generationConfig))
         .validate()
@@ -58,6 +85,13 @@ internal constructor(
       throw FirebaseVertexAIException.from(e)
     }
 
+  /**
+   * Generates an image, storing the result in Google Cloud Storage and returning a URL
+   *
+   * @param prompt The input(s) given to the model as a prompt.
+   * @param gcsUri Specifies where in Google Cloud Storage to store the image (for example, a
+   * specific bucket or folder).
+   */
   public suspend fun generateImages(
     prompt: String,
     gcsUri: String,

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/internal/GenerateImageRequest.kt

@@ -1,3 +1,19 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package com.google.firebase.vertexai.internal
 
 import com.google.firebase.vertexai.common.Request

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/internal/GenerateImageResponse.kt

@@ -1,3 +1,19 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package com.google.firebase.vertexai.internal
 
 import kotlinx.serialization.Serializable

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/internal/util/AppCheckHeaderProvider.kt

@@ -1,3 +1,19 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package com.google.firebase.vertexai.internal.util
 
 import android.util.Log

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

@@ -1,11 +1,33 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package com.google.firebase.vertexai.type
 
+/** Represents the aspect ratio that the generated image should conform to. */
 public class ImagenAspectRatio private constructor(internal val internalVal: String) {
   public companion object {
+    /** A square image, useful for icons, profile pictures, etc. */
     @JvmField public val SQUARE_1x1: ImagenAspectRatio = ImagenAspectRatio("1:1")
+    /** A portrait image in 3:4, the aspect ratio of older TVs. */
     @JvmField public val PORTRAIT_3x4: ImagenAspectRatio = ImagenAspectRatio("3:4")
+    /** A landscape image in 4:3, the aspect ratio of older TVs. */
     @JvmField public val LANDSCAPE_4x3: ImagenAspectRatio = ImagenAspectRatio("4:3")
+    /** A portrait image in 9:16, the aspect ratio of modern monitors and phone screens. */
     @JvmField public val PORTRAIT_9x16: ImagenAspectRatio = ImagenAspectRatio("9:16")
+    /** A landscape image in 16:9, the aspect ratio of modern monitors and phone screens. */
     @JvmField public val LANDSCAPE_16x9: ImagenAspectRatio = ImagenAspectRatio("16:9")
   }
 }

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

@@ -1,4 +1,26 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package com.google.firebase.vertexai.type
 
+/**
+ * Represents an Imagen-generated image that is contained in Google Cloud Storage.
+ *
+ * @param gcsUri Contains the `gs://` URI for the image.
+ * @param mimeType Contains the MIME type of the image (for example, `"image/png"`).
+ */
 public class ImagenGCSImage
 internal constructor(public val gcsUri: String, public val mimeType: String) {}

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

@@ -1,19 +1,64 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package com.google.firebase.vertexai.type
 
+/**
+ * Contains extra settings to configure image generation.
+ *
+ * @param negativePrompt This string contains things that should be explicitly excluded from
+ * generated images.
+ * @param numberOfImages How many images should be generated.
+ * @param aspectRatio The aspect ratio of the generated images.
+ * @param imageFormat The file format/compression of the generated images.
+ * @param addWatermark Adds an invisible watermark to mark the image as AI generated.
+ */
 public class ImagenGenerationConfig(
   public val negativePrompt: String? = null,
   public val numberOfImages: Int? = 1,
   public val aspectRatio: ImagenAspectRatio? = null,
   public val imageFormat: ImagenImageFormat? = null,
   public val addWatermark: Boolean? = null,
 ) {
+  /**
+   * Builder for creating a [ImagenGenerationConfig].
+   *
+   * This is mainly intended for Java interop. For Kotlin, use [imagenGenerationConfig] for a
+   * more idiomatic experience.
+   *
+   * @property negativePrompt See [ImagenGenerationConfig.negativePrompt].
+   * @property numberOfImages See [ImagenGenerationConfig.numberOfImages].
+   * @property aspectRatio See [ImagenGenerationConfig.aspectRatio].
+   * @property imageFormat See [ImagenGenerationConfig.imageFormat]
+   * @property addWatermark See [ImagenGenerationConfig.addWatermark]
+   * @see [imagenGenerationConfig]
+   */
   public class Builder {
     @JvmField public var negativePrompt: String? = null
     @JvmField public var numberOfImages: Int? = 1
     @JvmField public var aspectRatio: ImagenAspectRatio? = null
     @JvmField public var imageFormat: ImagenImageFormat? = null
     @JvmField public var addWatermark: Boolean? = null
 
+    /**
+     * Alternative casing for [ImagenGenerationConfig.Builder]:
+     * ```
+     * val config = GenerationConfig.builder()
+     * ```
+     */
     public fun build(): ImagenGenerationConfig =
       ImagenGenerationConfig(
         negativePrompt = negativePrompt,
@@ -29,6 +74,20 @@ public class ImagenGenerationConfig(
   }
 }
 
+/**
+ * Helper method to construct a [ImagenGenerationConfig] in a DSL-like manner.
+ *
+ * Example Usage:
+ * ```
+ * imagenGenerationConfig {
+ *   negativePrompt = "People, black and white, painting"
+ *   numberOfImages = 1
+ *   aspectRatio = ImagenAspecRatio.SQUARE_1x1
+ *   imageFormat = ImagenImageFormat.png()
+ *   addWatermark = false
+ * }
+ * ```
+ */
 public fun imagenGenerationConfig(
   init: ImagenGenerationConfig.Builder.() -> Unit
 ): ImagenGenerationConfig {

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

@@ -1,4 +1,27 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package com.google.firebase.vertexai.type
 
+/**
+ * Represents a response from a call to [ImagenModel#generateImages]
+ *
+ * @param images contains the generated images
+ * @param filteredReason if fewer images were generated than were requested, this field will contain
+ * the reason they were filtered out.
+ */
 public class ImagenGenerationResponse<T>
 internal constructor(public val images: List<T>, public val filteredReason: String?) {}

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

@@ -1,13 +1,43 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package com.google.firebase.vertexai.type
 
+/**
+ * Represents the format an image should be returned in.
+ * @param mimeType A string (like `"image/jpeg"`) specifying the encoding MIME type of the image.
+ * @param compressionQuality an int (1-100) representing the quality of the image; a lower number
+ * means the image is permitted to be lower quality to reduce size. This parameter is not relevant
+ * for every MIME type.
+ */
 public class ImagenImageFormat
 private constructor(public val mimeType: String, public val compressionQuality: Int?) {
 
   public companion object {
+    /**
+     * An [ImagenImageFormat] representing a JPEG image.
+     *
+     * @param compressionQuality an int (1-100) representing the quality of the image; a lower
+     * number means the image is permitted to be lower quality to reduce size.
+     */
     public fun jpeg(compressionQuality: Int? = null): ImagenImageFormat {
       return ImagenImageFormat("image/jpeg", compressionQuality)
     }
 
+    /** An [ImagenImageFormat] representing a PNG image */
     public fun png(): ImagenImageFormat {
       return ImagenImageFormat("image/png", null)
     }