PR feedback - refdoc and comment cleanup

Author: MarkDuckworth

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

@@ -3593,11 +3593,23 @@ export class Field
   // }
 
   /**
+   * @beta
+   *
    * Evaluates to the distance in meters between the location specified
    * by this field and the query location.
    *
    * @remarks This Expression can only be used within a `Search` stage.
    *
+   * @example
+   * ```typescript
+   * const geoDistanceToUser = field('location').geoDistance(new GeoPoint(39.7541, -105.0002));
+   *
+   * db.pipeline().collection('restaurants').search({
+   *   query: geoDistanceToUser.lessThanOrEqual(2000),
+   *   sort: geoDistanceToUser.ascending()
+   * })
+   * ```
+   *
    * @param location - Compute distance to this GeoPoint.
    * @returns An `Expression` representing the geoDistance function.
    */
@@ -10991,8 +11003,8 @@ export function documentMatches(
  *
  * Evaluates to the search score that reflects the topicality of the document
  * to all the text predicates (for example: `documentMatches`)
- * in the search query. If `SearchOptions.query` is not set or does not contain
- * any text predicates, then this score will always be `0`.
+ * in the search `query` provided to the `search` stage. If the `query` provided to the search stage
+ * is not set or does not contain any text predicates, then this score will always be `0`.
  *
  * @remarks This Expression can only be used within a `Search` stage.
  *

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

@@ -1422,6 +1422,13 @@ export class Pipeline implements firestore.Pipelines.Pipeline {
    * @remarks This must be the first stage of the pipeline.
    * @remarks A limited set of expressions are supported in the search stage.
    *
+   * @example
+   * ```typescript
+   * db.pipeline().collection('restaurants').search({
+   *   query: documentMatches('breakfast')
+   * })
+   * ```
+   *
    * @param options - An object that specifies required and optional parameters
    *                  for the stage.
    * @return A new `Pipeline` object with this stage appended to the stage list.
@@ -1431,6 +1438,7 @@ export class Pipeline implements firestore.Pipelines.Pipeline {
     const normalizedQuery: BooleanExpression = isExpr(options.query)
       ? (options.query as BooleanExpression)
       : documentMatches(options.query);
+    // TODO(search) - re-enable select normalization when select is supported in the API
     // const normalizedSelect: Record<string, Expression> | undefined =
     //   options.select ? selectablesToObject(options.select) : undefined;
     const normalizedAddFields: Record<string, Expression> | undefined =
@@ -1442,6 +1450,7 @@ export class Pipeline implements firestore.Pipelines.Pipeline {
     const internalOptions: InternalSearchStageOptions = {
       ...options,
       query: normalizedQuery,
+      // TODO(search) - re-enable select normalization when select is supported in the API
       // select: normalizedSelect,
       addFields: normalizedAddFields,
       sort: normalizedSort,

handwritten/firestore/types/firestore.d.ts

@@ -6073,6 +6073,16 @@ declare namespace FirebaseFirestore {
        *
        * @remarks This Expression can only be used within a `Search` stage.
        *
+       * @example
+       * ```typescript
+       * const geoDistanceToUser = field('location').geoDistance(new GeoPoint(39.7541, -105.0002));
+       *
+       * db.pipeline().collection('restaurants').search({
+       *   query: geoDistanceToUser.lessThanOrEqual(2000),
+       *   sort: geoDistanceToUser.ascending()
+       * })
+       * ```
+       *
        * @param location - Compute distance to this GeoPoint.
        */
       geoDistance(location: GeoPoint | Expression): Expression;
@@ -13207,6 +13217,26 @@ declare namespace FirebaseFirestore {
        * @returns A new {@code Pipeline} object with this stage appended to the stage list.
        */
       unnest(options: UnnestStageOptions): Pipeline;
+      /**
+       * @beta
+       *
+       * Add a search stage to the Pipeline.
+       *
+       * @remarks This must be the first stage of the pipeline.
+       * @remarks A limited set of expressions are supported in the search stage.
+       *
+       * @example
+       * ```typescript
+       * db.pipeline().collection('restaurants').search({
+       *   query: documentMatches('breakfast')
+       * })
+       * ```
+       *
+       * @param options - An object that specifies required and optional parameters
+       *                  for the stage.
+       * @return A new `Pipeline` object with this stage appended to the stage list.
+       */
+      search(options: SearchStageOptions): Pipeline;
       /**
        * @beta
        * Sorts the documents from previous stages based on one or more `Ordering` criteria.
@@ -13758,7 +13788,7 @@ declare namespace FirebaseFirestore {
        * @example
        * ```typescript
        * db.pipeline().collection('restaurants').search({
-       *   query: documentMatches("breakfast")
+       *   query: documentMatches('breakfast')
        * })
        * ```
        *