Add docsgen podspec for VertexAI and clean up some doc comments (#12912)

FirebaseVertexAI-Docs.podspec

@@ -0,0 +1,55 @@
+Pod::Spec.new do |s|
+  s.name             = 'FirebaseVertexAI'
+  s.version          = '10.26.0'
+  s.summary          = 'Firebase VertexAI'
+
+  s.description      = <<-DESC
+  Placeholder podspec for docsgen only. Do not use this pod.
+                        DESC
+
+  s.homepage         = 'https://firebase.google.com'
+  s.license          = { :type => 'Apache-2.0', :file => 'LICENSE' }
+  s.authors          = 'Google, Inc.'
+
+  s.source           = {
+    :git => 'https://github.com/firebase/firebase-ios-sdk.git',
+    # TODO: this should be `'CocoaPods-' + s.version.to_s` (after May 14 2024)
+    :tag => 'release-10.26'
+  }
+
+  s.social_media_url = 'https://twitter.com/Firebase'
+
+  ios_deployment_target = '15.0'
+  osx_deployment_target = '10.14'
+
+  s.ios.deployment_target = ios_deployment_target
+  s.osx.deployment_target = osx_deployment_target
+
+  s.cocoapods_version = '>= 1.12.0'
+  s.prefix_header_file = false
+
+  s.source_files = [
+    'FirebaseVertexAI/Sources/**/*.swift',
+    'FirebaseCore/Extension/*.h',
+    'FirebaseAuth/Interop/*.h',
+  ]
+
+  s.swift_version = '5.3'
+
+  s.framework = 'Foundation'
+  s.ios.framework = 'UIKit'
+  s.osx.framework = 'AppKit'
+  s.tvos.framework = 'UIKit'
+  s.watchos.framework = 'WatchKit'
+
+  s.dependency 'FirebaseCore', '~> 10.0'
+  s.dependency 'FirebaseCoreExtension'
+  s.dependency 'FirebaseAuthInterop'
+  s.dependency 'FirebaseAppCheckInterop', '~> 10.17'
+
+  s.pod_target_xcconfig = {
+    'GCC_C_LANGUAGE_STANDARD' => 'c99',
+    'HEADER_SEARCH_PATHS' => '"${PODS_TARGET_SRCROOT}"',
+    'OTHER_CFLAGS' => '-fno-autolink'
+  }
+end

FirebaseVertexAI/Sources/Chat.swift

@@ -30,7 +30,11 @@ public class Chat {
   /// model. This will be provided to the model for each message sent as context for the discussion.
   public var history: [ModelContent]
 
-  /// See ``sendMessage(_:)-3ify5``.
+  /// Sends a message using the existing history of this chat as context. If successful, the message
+  /// and response will be added to the history. If unsuccessful, history will remain unchanged.
+  /// - Parameter parts: The new content to send as a single chat message.
+  /// - Returns: The model's response if no error occurred.
+  /// - Throws: A ``GenerateContentError`` if an error occurred.
   public func sendMessage(_ parts: any ThrowingPartsRepresentable...) async throws
     -> GenerateContentResponse {
     return try await sendMessage([ModelContent(parts: parts)])
@@ -76,7 +80,10 @@ public class Chat {
     return result
   }
 
-  /// See ``sendMessageStream(_:)-4abs3``.
+  /// Sends a message using the existing history of this chat as context. If successful, the message
+  /// and response will be added to the history. If unsuccessful, history will remain unchanged.
+  /// - Parameter parts: The new content to send as a single chat message.
+  /// - Returns: A stream containing the model's response or an error if an error occurred.
   @available(macOS 12.0, *)
   public func sendMessageStream(_ parts: any ThrowingPartsRepresentable...)
     -> AsyncThrowingStream<GenerateContentResponse, Error> {

FirebaseVertexAI/Sources/GenerativeAIService.swift

@@ -19,10 +19,10 @@ import Foundation
 
 @available(iOS 15.0, macOS 11.0, macCatalyst 15.0, *)
 struct GenerativeAIService {
-  /// The language of the SDK in the format "gl-<language>/<version>".
+  /// The language of the SDK in the format `gl-<language>/<version>`.
   static let languageTag = "gl-swift/5"
 
-  /// The Firebase SDK version in the format "fire/<version>".
+  /// The Firebase SDK version in the format `fire/<version>`.
   static let firebaseVersionTag = "fire/\(FirebaseVersion())"
 
   /// Gives permission to talk to the backend.

FirebaseVertexAI/Sources/GenerativeAISwift.swift

@@ -18,8 +18,9 @@ import Foundation
   #warning("Only iOS, macOS, and Catalyst targets are currently fully supported.")
 #endif
 
-/// Constants associated with the GenerativeAISwift SDK
+/// Constants associated with the GenerativeAISwift SDK.
 @available(iOS 15.0, macOS 11.0, macCatalyst 15.0, *)
 public enum GenerativeAISwift {
+  /// The Vertex AI backend endpoint URL.
   static let baseURL = "https://firebaseml.googleapis.com"
 }

FirebaseVertexAI/Sources/GenerativeModel.swift

@@ -50,7 +50,7 @@ public final class GenerativeModel {
   /// Initializes a new remote model with the given parameters.
   ///
   /// - Parameters:
-  ///   - name: The name of the model to use, e.g., `"gemini-1.0-pro"`; see
+  ///   - name: The name of the model to use, for example `"gemini-1.0-pro"`; see
   ///     [Gemini models](https://ai.google.dev/models/gemini) for a list of supported model names.
   ///   - apiKey: The API key for your project.
   ///   - generationConfig: The content generation parameters your model should use.
@@ -104,7 +104,7 @@ public final class GenerativeModel {
   /// [zero-shot](https://developers.google.com/machine-learning/glossary/generative#zero-shot-prompting)
   /// or "direct" prompts. For
   /// [few-shot](https://developers.google.com/machine-learning/glossary/generative#few-shot-prompting)
-  /// prompts, see ``generateContent(_:)-58rm0``.
+  /// prompts, see `generateContent(_ content: @autoclosure () throws -> [ModelContent])`.
   ///
   /// - Parameter content: The input(s) given to the model as a prompt (see
   /// ``ThrowingPartsRepresentable``
@@ -163,7 +163,7 @@ public final class GenerativeModel {
   /// [zero-shot](https://developers.google.com/machine-learning/glossary/generative#zero-shot-prompting)
   /// or "direct" prompts. For
   /// [few-shot](https://developers.google.com/machine-learning/glossary/generative#few-shot-prompting)
-  /// prompts, see ``generateContent(_:)-58rm0``.
+  /// prompts, see `generateContentStream(_ content: @autoclosure () throws -> [ModelContent])`.
   ///
   /// - Parameter content: The input(s) given to the model as a prompt (see
   /// ``ThrowingPartsRepresentable``
@@ -252,7 +252,7 @@ public final class GenerativeModel {
   /// [zero-shot](https://developers.google.com/machine-learning/glossary/generative#zero-shot-prompting)
   /// or "direct" prompts. For
   /// [few-shot](https://developers.google.com/machine-learning/glossary/generative#few-shot-prompting)
-  /// input, see ``countTokens(_:)-9spwl``.
+  /// input, see `countTokens(_ content: @autoclosure () throws -> [ModelContent])`.
   ///
   /// - Parameter content: The input(s) given to the model as a prompt (see
   /// ``ThrowingPartsRepresentable``
@@ -306,7 +306,7 @@ public final class GenerativeModel {
   }
 }
 
-/// See ``GenerativeModel/countTokens(_:)-9spwl``.
+/// An error thrown in `GenerativeModel.countTokens(_:)`.
 @available(iOS 15.0, macOS 11.0, macCatalyst 15.0, *)
 public enum CountTokensError: Error {
   case internalError(underlying: Error)

FirebaseVertexAI/Sources/VertexAI.swift

@@ -20,6 +20,7 @@ import Foundation
 // Avoids exposing internal FirebaseCore APIs to Swift users.
 @_implementationOnly import FirebaseCoreExtension
 
+/// The Vertex AI service for Firebase.
 @available(iOS 15.0, macOS 11.0, macCatalyst 15.0, *)
 public class VertexAI: NSObject {
   // MARK: - Public APIs
@@ -59,9 +60,8 @@ public class VertexAI: NSObject {
   /// Initializes a generative model with the given parameters.
   ///
   /// - Parameters:
-  ///   - modelName: The name of the model to use, e.g., `"gemini-1.0-pro"`; see
-  ///     [Gemini
-  ///     models](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#gemini-models)
+  ///   - modelName: The name of the model to use, for example `"gemini-1.0-pro"`; see
+  ///     [Gemini models](https://firebase.google.com/docs/vertex-ai/gemini-model#available-models)
   ///     for a list of supported model names.
   ///   - generationConfig: The content generation parameters your model should use.
   ///   - safetySettings: A value describing what types of harmful content your model should allow.