add documentation

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

@@ -18,6 +18,23 @@
   @_exported import FirebaseFirestoreInternal
 #endif // SWIFT_PACKAGE
 
+///
+/// A `Constant` is an `Expression` that represents a fixed, literal value within a Firestore pipeline.
+///
+/// `Constant`s are used to introduce literal values into a query, which can be useful for:
+/// - Comparing a field to a specific value in a `where` clause.
+/// - Adding new fields with fixed values using `addFields`.
+/// - Providing literal arguments to functions like `sum` or `average`.
+///
+/// Example of using a `Constant` to add a new field:
+/// ```swift
+/// // Add a new field "source" with the value "manual" to each document
+/// firestore.pipeline()
+///   .collection("entries")
+///   .addFields([
+///     Constant("manual").as("source")
+///   ])
+/// ```
 public struct Constant: Expression, BridgeWrapper, @unchecked Sendable {
   let bridge: ExprBridge
 
@@ -33,55 +50,78 @@ public struct Constant: Expression, BridgeWrapper, @unchecked Sendable {
     }
   }
 
-  // Initializer for integer
+  /// Creates a new `Constant` expression from an integer literal.
+  ///
+  /// - Parameter value: The integer value.
   public init(_ value: Int) {
     self.init(value as Any)
   }
 
-  // Initializer for double
+  /// Creates a new `Constant` expression from a double-precision floating-point literal.
+  ///
+  /// - Parameter value: The double value.
   public init(_ value: Double) {
     self.init(value as Any)
   }
 
-  // Initializer for strings
+  /// Creates a new `Constant` expression from a string literal.
+  ///
+  /// - Parameter value: The string value.
   public init(_ value: String) {
     self.init(value as Any)
   }
 
-  // Initializer for boolean values
+  /// Creates a new `Constant` expression from a boolean literal.
+  ///
+  /// - Parameter value: The boolean value.
   public init(_ value: Bool) {
     self.init(value as Any)
   }
 
-  // Initializer for Bytes
+  /// Creates a new `Constant` expression from a `Data` (bytes) literal.
+  ///
+  /// - Parameter value: The `Data` value.
   public init(_ value: Data) {
     self.init(value as Any)
   }
 
-  // Initializer for GeoPoint values
+  /// Creates a new `Constant` expression from a `GeoPoint` literal.
+  ///
+  /// - Parameter value: The `GeoPoint` value.
   public init(_ value: GeoPoint) {
     self.init(value as Any)
   }
 
-  // Initializer for Timestamp values
+  /// Creates a new `Constant` expression from a `Timestamp` literal.
+  ///
+  /// - Parameter value: The `Timestamp` value.
   public init(_ value: Timestamp) {
     self.init(value as Any)
   }
 
-  // Initializer for Date values
+  /// Creates a new `Constant` expression from a `Date` literal.
+  ///
+  /// The `Date` will be converted to a `Timestamp` internally.
+  ///
+  /// - Parameter value: The `Date` value.
   public init(_ value: Date) {
     self.init(value as Any)
   }
 
-  // Initializer for DocumentReference
+  /// Creates a new `Constant` expression from a `DocumentReference` literal.
+  ///
+  /// - Parameter value: The `DocumentReference` value.
   public init(_ value: DocumentReference) {
     self.init(value as Any)
   }
 
-  // Initializer for vector values
+  /// Creates a new `Constant` expression from a `VectorValue` literal.
+  ///
+  /// - Parameter value: The `VectorValue` value.
   public init(_ value: VectorValue) {
     self.init(value as Any)
   }
 
+  /// A `Constant` representing a `nil`  value.
   public static let `nil` = Constant(nil)
 }

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

@@ -12,6 +12,26 @@
 // 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.
+/// A `Field` can be used to:
+/// - Reference a document field by its name or `FieldPath`.
+/// - Create complex `BooleanExpression`s for filtering in a `where` clause.
+/// - Perform mathematical operations on numeric fields.
+/// - Manipulate string and array fields.
+///
+/// Example of creating a `Field` and using it in a `where` clause:
+/// ```swift
+/// // Reference the "price" field in a document
+/// let priceField = Field("price")
+///
+/// // Create a query to find products where the price is greater than 100
+/// firestore.pipeline()
+///   .collection("products")
+///   .where(priceField.greaterThan(100))
+/// ```
 public struct Field: Expression, Selectable, BridgeWrapper, SelectableWrapper,
   @unchecked Sendable {
   let bridge: ExprBridge
@@ -24,13 +44,15 @@ public struct Field: Expression, Selectable, BridgeWrapper, SelectableWrapper,
 
   public let fieldName: String
 
+  /// Creates a new `Field` expression from a field name.
   public init(_ name: String) {
     let fieldBridge = FieldBridge(name: name)
     bridge = fieldBridge
     fieldName = fieldBridge.field_name()
     alias = fieldName
   }
 
+  /// Creates a new `Field` expression from a `FieldPath`.
   public init(_ path: FieldPath) {
     let fieldBridge = FieldBridge(path: path)
     bridge = fieldBridge

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

@@ -12,7 +12,22 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+///
+/// A `RandomExpression` is a `FunctionExpression` that generates a random floating-point
+/// number between 0.0 (inclusive) and 1.0 (exclusive).
+///
+/// This expression is useful when you need to introduce a random value into a pipeline,
+/// for example, to randomly sample a subset of documents.
+///
+/// Example of using `RandomExpression` to sample documents:
+/// ```swift
+/// // Create a query to sample approximately 10% of the documents in a collection
+/// firestore.pipeline()
+///   .collection("users")
+///   .where(RandomExpression().lessThan(0.1))
+/// ```
 public class RandomExpression: FunctionExpression, @unchecked Sendable {
+  /// Creates a new `RandomExpression` that generates a random number.
   public init() {
     super.init("rand", [])
   }