add documentations

Author: cherylEnkidu

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

@@ -22,13 +22,33 @@
 import Foundation
 
 @objc public extension Firestore {
+  /// Creates a `PipelineSource` that can be used to build and execute a pipeline of operations on the Firestore database.
+  ///
+  /// A pipeline is a sequence of stages that are executed in order. Each stage can perform an operation on the data, such as filtering, sorting, or transforming it.
+  ///
+  /// Example usage:
+  /// ```swift
+  /// let db = Firestore.firestore()
+  /// let pipeline = db.pipeline()
+  ///   .collection("books")
+  ///   .where(Field("rating").isGreaterThan(4.5))
+  ///   .sort([Field("rating").descending()])
+  ///   .limit(2)
+  /// ```
+  ///
+  /// - Returns: A `PipelineSource` that can be used to build and execute a pipeline.
   @available(iOS 13, tvOS 13, macOS 10.15, macCatalyst 13, watchOS 7, *)
   @nonobjc func pipeline() -> PipelineSource {
     return PipelineSource(db: self) { stages, db in
       Pipeline(stages: stages, db: db)
     }
   }
 
+  /// Creates a `RealtimePipelineSource` for building and executing a realtime pipeline.
+  ///
+  /// This is an internal method and should not be used directly.
+  ///
+  /// - Returns: A `RealtimePipelineSource` for building a realtime pipeline.
   @available(iOS 13, tvOS 13, macOS 10.15, macCatalyst 13, watchOS 7, *)
   @nonobjc internal func realtimePipeline() -> RealtimePipelineSource {
     return RealtimePipelineSource(db: self) { stages, db in

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

@@ -18,13 +18,23 @@ extension AggregateFunction {
   }
 }
 
+/// Represents an aggregate function in a pipeline.
+///
+/// An `AggregateFunction` is a function that computes a single value from a set of input values.
+///
+/// `AggregateFunction`s are typically used in the `aggregate` stage of a pipeline.
 public class AggregateFunction: AggregateBridgeWrapper, @unchecked Sendable {
   let bridge: AggregateFunctionBridge
 
   let functionName: String
   let args: [Expression]
 
-  public init(_ functionName: String, _ args: [Expression]) {
+  /// Creates a new `AggregateFunction`.
+  ///
+  /// - Parameters:
+  ///   - functionName: The name of the aggregate function.
+  ///   - args: The arguments to the aggregate function.
+  public init(functionName: String, args: [Expression]) {
     self.functionName = functionName
     self.args = args
     bridge = AggregateFunctionBridge(
@@ -34,6 +44,10 @@ public class AggregateFunction: AggregateBridgeWrapper, @unchecked Sendable {
     )
   }
 
+  /// Creates an `AliasedAggregate` from this aggregate function.
+  ///
+  /// - Parameter name: The alias for the aggregate function.
+  /// - Returns: An `AliasedAggregate` with the given alias.
   public func `as`(_ name: String) -> AliasedAggregate {
     return AliasedAggregate(aggregate: self, alias: name)
   }

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

@@ -12,7 +12,9 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+/// An `AggregateFunction` that has been given an alias.
 public struct AliasedAggregate {
-  public let aggregate: AggregateFunction
-  public let alias: String
+  let aggregate: AggregateFunction
+  
+  let alias: String
 }

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

@@ -38,6 +38,6 @@
 public class CountAll: AggregateFunction, @unchecked Sendable {
   /// Initializes a new `CountAll` aggregation.
   public init() {
-    super.init("count", [])
+    super.init(functionName: "count", args: [])
   }
 }

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

@@ -20,6 +20,7 @@
 
 import Foundation
 
+/// Represents the distance measure to be used in a vector similarity search.
 public struct DistanceMeasure: Sendable, Equatable, Hashable {
   let kind: Kind
 
@@ -29,10 +30,13 @@ public struct DistanceMeasure: Sendable, Equatable, Hashable {
     case dotProduct = "dot_product"
   }
 
+  /// The Euclidean distance measure.
   public static let euclidean: DistanceMeasure = .init(kind: .euclidean)
 
+  /// The Cosine distance measure.
   public static let cosine: DistanceMeasure = .init(kind: .cosine)
 
+  /// The Dot Product distance measure.
   public static let dotProduct: DistanceMeasure = .init(kind: .dotProduct)
 
   init(kind: Kind) {

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

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+/// An `Expression` that has been given an alias.
 public struct AliasedExpression: Selectable, SelectableWrapper, Sendable {
   let alias: String
 

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

@@ -12,7 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-///
 /// A `Field` is an `Expression` that represents a field in a Firestore document.
 ///
 /// It is a central component for building queries and transformations in Firestore pipelines.
@@ -42,9 +41,12 @@ public struct Field: Expression, Selectable, BridgeWrapper, SelectableWrapper,
     return self
   }
 
+  /// The name of the field.
   public let fieldName: String
 
   /// Creates a new `Field` expression from a field name.
+  ///
+  /// - Parameter name: The name of the field.
   public init(_ name: String) {
     let fieldBridge = FieldBridge(name: name)
     bridge = fieldBridge
@@ -53,6 +55,8 @@ public struct Field: Expression, Selectable, BridgeWrapper, SelectableWrapper,
   }
 
   /// Creates a new `Field` expression from a `FieldPath`.
+  ///
+  /// - Parameter path: The `FieldPath` of the field.
   public init(_ path: FieldPath) {
     let fieldBridge = FieldBridge(path: path)
     bridge = fieldBridge

Firestore/Swift/Source/SwiftAPI/Pipeline/Expressions/FunctionExpressions/FunctionExpression.swift

@@ -12,12 +12,22 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+/// Represents a function call in a pipeline.
+///
+/// A `FunctionExpression` is an expression that represents a function call with a given name and arguments.
+///
+/// `FunctionExpression`s are typically used to perform operations on data in a pipeline, such as mathematical calculations, string manipulations, or array operations.
 public class FunctionExpression: Expression, BridgeWrapper, @unchecked Sendable {
   let bridge: ExprBridge
 
   let functionName: String
   let args: [Expression]
 
+  /// Creates a new `FunctionExpression`.
+  ///
+  /// - Parameters:
+  ///   - functionName: The name of the function.
+  ///   - args: The arguments to the function.
   public init(functionName: String, args: [Expression]) {
     self.functionName = functionName
     self.args = args

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

@@ -14,9 +14,13 @@
  * limitations under the License.
  */
 
+/// An ordering for the documents in a pipeline.
 public struct Ordering: @unchecked Sendable {
+  /// The expression to order by.
   public let expression: Expression
+  /// The direction to order in.
   public let direction: Direction
+  
   let bridge: OrderingBridge
 
   init(expression: Expression, direction: Direction) {
@@ -26,6 +30,7 @@ public struct Ordering: @unchecked Sendable {
   }
 }
 
+/// A direction to order results in.
 public struct Direction: Sendable, Equatable, Hashable {
   let kind: Kind
   public let rawValue: String
@@ -35,8 +40,10 @@ public struct Direction: Sendable, Equatable, Hashable {
     case descending
   }
 
+  /// The ascending direction.
   static let ascending = Direction(kind: .ascending, rawValue: "ascending")
 
+  /// The descending direction.
   static let descending = Direction(kind: .descending, rawValue: "descending")
 
   init(kind: Kind, rawValue: String) {

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

@@ -24,16 +24,11 @@ import Foundation
 ///
 /// A pipeline takes data sources, such as Firestore collections or collection groups, and applies
 /// a series of stages that are chained together. Each stage takes the output from the previous
-/// stage
-/// (or the data source) and produces an output for the next stage (or as the final output of the
+/// stage (or the data source) and produces an output for the next stage (or as the final output of the
 /// pipeline).
 ///
 /// Expressions can be used within each stage to filter and transform data through the stage.
 ///
-/// NOTE: The chained stages do not prescribe exactly how Firestore will execute the pipeline.
-/// Instead, Firestore only guarantees that the result is the same as if the chained stages were
-/// executed in order.
-///
 /// ## Usage Examples
 ///
 /// The following examples assume you have a `Firestore` instance named `db`.
@@ -88,6 +83,7 @@ public struct Pipeline: @unchecked Sendable {
     bridge = PipelineBridge(stages: stages.map { $0.bridge }, db: db)
   }
 
+  /// A `Pipeline.Snapshot` contains the results of a pipeline execution.
   public struct Snapshot: Sendable {
     /// An array of all the results in the `Pipeline.Snapshot`.
     public let results: [PipelineResult]