add documentations

Author: cherylEnkidu

Firestore/Swift/Source/SwiftAPI/Pipeline/Options/GenericOptions.swift

@@ -12,8 +12,13 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+/// A container for providing arbitrary, backend-specific options to a pipeline.
+///
+/// Use this to pass options that are not explicitly defined in the other option structs.
 public struct CustomOptions: OptionProtocol {
   var values: [String: Sendable]
+  /// Creates a set of custom options from a dictionary.
+  /// - Parameter values: A dictionary containing the custom options.
   public init(_ values: [String: Sendable] = [:]) {
     self.values = values
   }

Firestore/Swift/Source/SwiftAPI/Pipeline/Options/IndexMode.swift

@@ -12,9 +12,11 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+/// Specifies which indexes the pipeline should use for execution.
 public struct IndexMode: Sendable, Equatable, Hashable {
   let rawValue: String
 
+  /// Use the set of indexes recommended by the backend.
   public static let recommended = IndexMode(rawValue: "recommended")
 
   init(rawValue: String) {

Firestore/Swift/Source/SwiftAPI/Pipeline/Options/OptionProtocol.swift

@@ -12,4 +12,5 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+/// A protocol that all pipeline option types must conform to.
 public protocol OptionProtocol: Sendable {}

Firestore/Swift/Source/SwiftAPI/Pipeline/Pipeline.swift

@@ -107,6 +107,14 @@ public struct Pipeline: @unchecked Sendable {
   /// }
   /// ```
   ///
+  /// - Parameters:
+  ///   - explainOptions: Configures the execution plan report for debugging and optimization. Use
+  /// it to analyze performance, get index recommendations, and control the verbosity and format of
+  /// the output.
+  ///   - indexMode: Specifies which indexes to use for the pipeline, such as the `.recommended`
+  /// set.
+  ///   - customOptions: A dictionary for passing any other backend-specific or advanced options to
+  /// the pipeline execution.
   /// - Throws: An error if the pipeline execution fails on the backend.
   /// - Returns: A `PipelineSnapshot` containing the result of the pipeline execution.
   public func execute(explainOptions: ExplainOptions? = nil,
@@ -149,7 +157,8 @@ public struct Pipeline: @unchecked Sendable {
   /// - Parameter field: The first field to add to the documents, specified as a `Selectable`.
   /// - Parameter additionalFields: Optional additional fields to add, specified as `Selectable`s.
   /// - Returns: A new `Pipeline` object with this stage appended.
-  public func addFields(_ field: Selectable, _ additionalFields: Selectable...) -> Pipeline {
+  public func addFields(_ field: Selectable, _ additionalFields: Selectable...,
+                        customOptions: [String: Sendable]? = nil) -> Pipeline {
     let fields = [field] + additionalFields
     return Pipeline(stages: stages + [AddFields(fields: fields)], db: db)
   }

Firestore/Swift/Tests/Integration/PipelineApiTests.swift

@@ -77,7 +77,8 @@ final class PipelineTests: FSTIntegrationTestCase {
     _ = db.pipeline().collection("books")
       .addFields(
         Field("msrp").multiply(Field("discount")).as("salePrice"),
-        Field("author")
+        Field("author"),
+        customOptions: ["option_not_known_to_sdk": true]
       )
 
     // Output