update jsdocs

Author: milaGGL

handwritten/firestore/api-report/firestore.api.md

@@ -499,10 +499,10 @@ function charLength(fieldName: string): FunctionExpression;
 function charLength(stringExpression: Expression): FunctionExpression;
 
 // @beta
-function coalesce(first: Expression, second: Expression | unknown, ...others: Array<Expression | unknown>): Expression;
+function coalesce(expression: Expression, replacement: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
 
 // @beta
-function coalesce(firstFieldName: string, second: Expression | unknown, ...others: Array<Expression | unknown>): Expression;
+function coalesce(fieldName: string, replacement: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
 
 // Warning: (tsdoc-undefined-tag) The TSDoc tag "@class" is not defined in this configuration
 //
@@ -1105,7 +1105,7 @@ abstract class Expression implements firestore.Pipelines.Expression, HasUserData
     byteLength(): FunctionExpression;
     ceil(): FunctionExpression;
     charLength(): FunctionExpression;
-    coalesce(second: Expression | unknown, ...others: Array<Expression | unknown>): Expression;
+    coalesce(replacement: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
     collectionId(): FunctionExpression;
     concat(second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
     cosineDistance(vectorExpression: Expression): FunctionExpression;
@@ -1142,8 +1142,8 @@ abstract class Expression implements firestore.Pipelines.Expression, HasUserData
     ifAbsent(elseExpression: unknown): Expression;
     ifError(catchExpr: Expression): FunctionExpression;
     ifError(catchValue: unknown): FunctionExpression;
-    ifNull(elseValue: unknown): Expression;
-    ifNull(elseExpression: unknown): Expression;
+    ifNull(elseExpression: Expression): FunctionExpression;
+    ifNull(elseValue: unknown): FunctionExpression;
     isAbsent(): BooleanExpression;
     isError(): BooleanExpression;
     isType(type: string): BooleanExpression;
@@ -1648,16 +1648,16 @@ function ifError(tryExpr: Expression, catchExpr: Expression): FunctionExpression
 function ifError(tryExpr: Expression, catchValue: unknown): FunctionExpression;
 
 // @beta
-function ifNull(ifExpr: Expression, elseExpr: Expression): Expression;
+function ifNull(ifExpr: Expression, elseExpr: Expression): FunctionExpression;
 
 // @beta
-function ifNull(ifExpr: Expression, elseValue: unknown): Expression;
+function ifNull(ifExpr: Expression, elseValue: unknown): FunctionExpression;
 
 // @beta
-function ifNull(ifFieldName: string, elseExpr: Expression): Expression;
+function ifNull(ifFieldName: string, elseExpr: Expression): FunctionExpression;
 
 // @beta
-function ifNull(ifFieldName: string, elseValue: unknown): Expression;
+function ifNull(ifFieldName: string, elseValue: unknown): FunctionExpression;
 
 // @beta
 function isAbsent(value: Expression): BooleanExpression;

handwritten/firestore/dev/src/pipelines/expression.ts

@@ -2881,35 +2881,41 @@ export abstract class Expression
    * Creates an expression that returns the `elseValue` argument if this expression results in a null value, else
    * return the result of this expression evaluation.
    *
+   * @remarks
+   * This function provides a fallback for both absent and explicit null values. In contrast, {@link ifAbsent}
+   * only triggers for missing fields.
+   *
    * @example
    * ```typescript
-   * // Returns the value of the 'optional_field', or returns 'default_value'
-   * // if the field is null.
-   * field("optional_field").ifNull("default_value")
+   * // Returns the user's preferred name, or if that is null or absent, returns their full name.
+   * field("preferredName").ifNull(field("fullName"))
    * ```
    *
-   * @param elseValue The value that will be returned if this Expression evaluates to a null value.
+   * @param elseExpression The Expression that will be evaluated if this Expression evaluates to a null or absent value.
    * @returns A new [Expression] representing the ifNull operation.
    */
-  ifNull(elseValue: unknown): Expression;
+  ifNull(elseExpression: Expression): FunctionExpression;
 
   /**
    * @beta
    * Creates an expression that returns the `elseValue` argument if this expression results in a null value, else
    * return the result of this expression evaluation.
    *
+   * @remarks
+   * This function provides a fallback for both absent and explicit null values. In contrast, {@link ifAbsent}
+   * only triggers for missing fields.
+   *
    * @example
    * ```typescript
-   * // Returns the value of the 'optional_field', or if that is
-   * // null, then returns the value of the field `
-   * field("optional_field").ifNull(field('default_field'))
+   * // Returns the user's display name, or returns "Anonymous" if the field is null or absent.
+   * field("displayName").ifNull("Anonymous")
    * ```
    *
-   * @param elseExpression The Expression that will be evaluated if this Expression evaluates to a null value.
+   * @param elseValue The value that will be returned if this Expression evaluates to a null or absent value.
    * @returns A new [Expression] representing the ifNull operation.
    */
-  ifNull(elseExpression: unknown): Expression;
-  ifNull(elseValueOrExpression: Expression | unknown): Expression {
+  ifNull(elseValue: unknown): FunctionExpression;
+  ifNull(elseValueOrExpression: Expression | unknown): FunctionExpression {
     return new FunctionExpression('if_null', [
       this,
       valueToDefaultExpr(elseValueOrExpression),
@@ -2918,26 +2924,25 @@ export abstract class Expression
 
   /**
    * @beta
-   * Creates an expression that Returns the first non-null, non-absent argument, without evaluating
+   * Creates an expression that returns the first non-null, non-absent argument, without evaluating
    * the rest of the arguments. When all arguments are null or absent, returns the last argument.
    *
    * @example
    * ```typescript
-   * // Return "Anonymous" if the 'name' field is null.
-   * field("name").coalesce("Anonymous");
-   * // Return "val1" if "val1" is not null, otherwise "val2", or "default" if both are null.
-   * field("val1").coalesce(field("val2"), "default");
+   * // Returns the value of the first non-null, non-absent field among 'preferredName', 'fullName',
+   * // or the last argument if all previous fields are null.
+   * field("preferredName").coalesce(field("fullName"), "Anonymous");
    * ```
    *
    * @param replacement - The value to use if this expression evaluates to null.
    * @param others - Optional additional values to check if previous values are null.
    * @returns A new [Expression] representing the coalesce operation.
    */
   coalesce(
-    second: Expression | unknown,
+    replacement: Expression | unknown,
     ...others: Array<Expression | unknown>
-  ): Expression {
-    const values = [second, ...others];
+  ): FunctionExpression {
+    const values = [replacement, ...others];
     return new FunctionExpression('coalesce', [
       this,
       ...values.map(valueToDefaultExpr),
@@ -9258,95 +9263,119 @@ export function ifAbsent(
 
 /**
  * @beta
- * Creates an expression that returns the `elseExpr` argument if `ifExpr` is null or absent, else
+ * Creates an expression that returns the `elseExpr` argument if `ifExpr` is null, else
  * return the result of the `ifExpr` argument evaluation.
  *
+ * @remarks
+ * This function provides a fallback for both absent and explicit null values. In contrast,
+ * {@link ifAbsent} only triggers for missing fields.
+ *
  * @example
  * ```typescript
- * // Returns the value of the 'optional_field', or returns value of the 'default_field'
- * // if the 'optional_field' value is null or absent.
- * ifNull(field("optional_field"), field("default_field"))
+ * // Returns the user's preferred name, or if that is null or absent, returns their full name.
+ * ifNull(field("preferredName"), field("fullName"))
  * ```
  *
  * @param ifExpr The expression to check for null or absence.
  * @param elseExpr The expression that will be evaluated and returned if `ifExpr` is null or absent.
  * @returns A new `Expression` representing the ifNull operation.
  */
-export function ifNull(ifExpr: Expression, elseExpr: Expression): Expression;
+export function ifNull(
+  ifExpr: Expression,
+  elseExpr: Expression,
+): FunctionExpression;
 
 /**
  * @beta
- * Creates an expression that returns the `elseValue` argument if `ifExpr` is null or absent, else
+ * Creates an expression that returns the `elseValue` argument if `ifExpr` is null, else
  * return the result of the `ifExpr` argument evaluation.
  *
+ * @remarks
+ * This function provides a fallback for both absent and explicit null values. In contrast,
+ * {@link ifAbsent} only triggers for missing fields.
+ *
  * @example
  * ```typescript
- * // Returns the value of the 'optional_field', or returns 'default_value'
- * // if the 'optional_field' value is null or absent.
- * ifNull(field("optional_field"), "default_value")
+ * // Returns the user's display name, or returns "Anonymous" if the field is null or absent.
+ * ifNull(field("displayName"), "Anonymous")
  * ```
  *
- * @param ifExpr The expression to check for absence.
+ * @param ifExpr The expression to check for null or absence.
  * @param elseValue The value that will be returned if `ifExpr` evaluates to a null or absent value.
  * @returns A new `Expression` representing the ifNull operation.
  */
-export function ifNull(ifExpr: Expression, elseValue: unknown): Expression;
+export function ifNull(
+  ifExpr: Expression,
+  elseValue: unknown,
+): FunctionExpression;
 
 /**
  * @beta
- * Creates an expression that returns the `elseExpr` argument if `ifFieldName` is null or absent, else
+ * Creates an expression that returns the `elseExpr` argument if `ifFieldName` is null, else
  * return the value of the field.
  *
+ * @remarks
+ * This function provides a fallback for both absent and explicit null values. In contrast,
+ * {@link ifAbsent} only triggers for missing fields.
+ *
  * @example
  * ```typescript
- * // Returns the value of the 'optional_field', or returns the value of
- * // 'default_field' if 'optional_field' is null or absent.
- * ifNull("optional_field", field("default_field"))
+ * // Returns the user's preferred name, or if that is null or absent, returns their full name.
+ * ifNull("preferredName", field("fullName"))
  * ```
  *
  * @param ifFieldName The field to check for null or absence.
  * @param elseExpr The expression that will be evaluated and returned if `ifFieldName` is
  * null or absent.
  * @returns A new `Expression` representing the ifNull operation.
  */
-export function ifNull(ifFieldName: string, elseExpr: Expression): Expression;
+export function ifNull(
+  ifFieldName: string,
+  elseExpr: Expression,
+): FunctionExpression;
 
 /**
  * @beta
- * Creates an expression that returns the `elseValue` argument if `ifFieldName` is null or absent, else
+ * Creates an expression that returns the `elseValue` argument if `ifFieldName` is null, else
  * return the value of the field.
  *
+ * @remarks
+ * This function provides a fallback for both absent and explicit null values. In contrast,
+ * {@link ifAbsent} only triggers for missing fields.
+ *
  * @example
  * ```typescript
- * // Returns the value of the 'optional_field', or returns 'default_value'
- * // if the field is null or absent.
- * ifNull("optional_field", "default_value")
+ * // Returns the user's display name, or returns "Anonymous" if the field is null or absent.
+ * ifNull("displayName", "Anonymous")
  * ```
  *
  * @param ifFieldName The field to check for null or absence.
  * @param elseValue The value that will be returned if `ifFieldName` is null or absent.
  * @returns A new `Expression` representing the ifNull operation.
  */
-export function ifNull(ifFieldName: string, elseValue: unknown): Expression;
+export function ifNull(
+  ifFieldName: string,
+  elseValue: unknown,
+): FunctionExpression;
 export function ifNull(
   fieldNameOrExpression: string | Expression,
   elseValue: Expression | unknown,
-): Expression {
+): FunctionExpression {
   return fieldOrExpression(fieldNameOrExpression).ifNull(
     valueToDefaultExpr(elseValue),
   );
 }
 
 /**
  * @beta
- * Returns the first non-null, non-absent argument, without evaluating
+ * Creates an expression that returns the first non-null, non-absent argument, without evaluating
  * the rest of the arguments. When all arguments are null or absent, returns the last argument.
  *
  * @example
  * ```typescript
- * // Returns the value of 'optional_field', or if that is
- * // null, then returns the value of 'default_field'
- * coalesce(field("optional_field"), field("default_field"))
+ * // Returns the value of the first non-null, non-absent field among 'preferredName', 'fullName',
+ * // or the last argument if all previous fields are null.
+ * coalesce(field("preferredName"), field("fullName"), constant("Anonymous"))
  * ```
  *
  * @param expression The first expression to check for null.
@@ -9358,18 +9387,18 @@ export function coalesce(
   expression: Expression,
   replacement: Expression | unknown,
   ...others: Array<Expression | unknown>
-): Expression;
+): FunctionExpression;
 
 /**
  * @beta
- * Returns the first non-null, non-absent argument, without evaluating
+ * Creates an expression that returns the first non-null, non-absent argument, without evaluating
  * the rest of the arguments. When all arguments are null or absent, returns the last argument.
  *
  * @example
  * ```typescript
- * // Returns the value of 'optional_field', or if that is
- * // null, then returns the value of 'default_field'
- * coalesce("optional_field", field("default_field"))
+ * // Returns the value of the first non-null, non-absent field among 'preferredName', 'fullName',
+ * // or the last argument if all previous fields are null.
+ * coalesce("preferredName", field("fullName"), constant("Anonymous"))
  * ```
  *
  * @param fieldName The name of the first field to check for null.
@@ -9381,14 +9410,16 @@ export function coalesce(
   fieldName: string,
   replacement: Expression | unknown,
   ...others: Array<Expression | unknown>
-): Expression;
-
+): FunctionExpression;
 export function coalesce(
-  first: Expression | string,
-  second: Expression | unknown,
+  fieldNameOrExpression: Expression | string,
+  replacement: Expression | unknown,
   ...others: Array<Expression | unknown>
-): Expression {
-  return fieldOrExpression(first).coalesce(second, ...others);
+): FunctionExpression {
+  return fieldOrExpression(fieldNameOrExpression).coalesce(
+    replacement,
+    ...others,
+  );
 }
 
 /**