Add documentation for ppl (#15401)

Co-authored-by: wu-hui <[email protected]>

Author: cherylEnkidu

Firestore/Swift/Source/ExpressionImplementation.swift

@@ -47,14 +47,14 @@ enum Helper {
       result.append(Constant(key))
       result.append(sendableToExpr(value))
     }
-    return FunctionExpression("map", result)
+    return FunctionExpression(functionName: "map", args: result)
   }
 
   static func array(_ elements: [Sendable?]) -> FunctionExpression {
     let transformedElements = elements.map { element in
       sendableToExpr(element)
     }
-    return FunctionExpression("array", transformedElements)
+    return FunctionExpression(functionName: "array", args: transformedElements)
   }
 
   // This function is used to convert Swift type into Objective-C type.

Firestore/Swift/Source/Helper/PipelineHelper.swift

@@ -22,13 +22,43 @@
 import Foundation
 
 @objc public extension Firestore {
+  /// Creates a new `PipelineSource` to build and execute a data pipeline.
+  ///
+  /// A pipeline is composed of a sequence of stages. Each stage processes the
+  /// output from the previous one, and the final stage's output is the result of the
+  /// pipeline's execution.
+  ///
+  /// Example usage:
+  /// ```swift
+  /// let pipeline = firestore.pipeline()
+  ///   .collection("books")
+  ///   .where(Field("rating").isGreaterThan(4.5))
+  ///   .sort(Field("rating").descending())
+  ///   .limit(2)
+  /// ```
+  ///
+  /// Note on Execution: The stages are conceptual. The Firestore backend may
+  /// optimize execution (e.g., reordering or merging stages) as long as the
+  /// final result remains the same.
+  ///
+  /// Important Limitations:
+  /// - Pipelines operate on a request/response basis only.
+  /// - They do not utilize or update the local SDK cache.
+  /// - They do not support realtime snapshot listeners.
+  ///
+  /// - Returns: A `PipelineSource` to begin defining the pipeline's stages.
   @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/Stages.swift renamed to Firestore/Swift/Source/Stages.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/Firestore+Pipeline.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/AggregateFunction.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/Aggregates/AliasedAggregate.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/Aggregates/CountAll.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