ref doc cleanup

Author: MarkDuckworth

google-cloud-firestore/src/main/java/com/google/cloud/firestore/pipeline/expressions/Expression.java

@@ -3412,6 +3412,14 @@ public static Expression geoDistance(String fieldName, GeoPoint location) {
    *
    * <p>This Expression can only be used within a {@code Search} stage.
    *
+   * <p>Example:
+   *
+   * <pre>{@code
+   * db.pipeline().collection("restaurants").search(
+   *   Search.withQuery("waffles").withSort(geoDistance(field("location"), new GeoPoint(37.0, -122.0)).ascending())
+   * )
+   * }</pre>
+   *
    * @param field Specifies the field in the document which contains the first {@link GeoPoint} for
    *     distance computation.
    * @param location Compute distance to this {@link GeoPoint}.
@@ -3428,7 +3436,13 @@ public static Expression geoDistance(Field field, GeoPoint location) {
    *
    * <p>This Expression can only be used within a {@code Search} stage.
    *
-   * @param rquery Define the search query using the search DTS.
+   * <p>Example:
+   *
+   * <pre>{@code
+   * db.pipeline().collection("restaurants").search(Search.withQuery(documentMatches("waffles OR pancakes")))
+   * }</pre>
+   *
+   * @param rquery Define the search query using the search DSL.
    * @return A new {@link BooleanExpression} representing the documentMatches operation.
    */
   @BetaApi
@@ -3441,8 +3455,14 @@ public static BooleanExpression documentMatches(String rquery) {
    *
    * <p>This Expression can only be used within a {@code Search} stage.
    *
+   * <p>Example:
+   *
+   * <pre>{@code
+   * db.pipeline().collection("restaurants").search(Search.withQuery(matches("menu", "waffles")))
+   * }</pre>
+   *
    * @param fieldName Perform search on this field.
-   * @param rquery Define the search query using the rquery DTS.
+   * @param rquery Define the search query using the search DSL.
    */
   @InternalApi
   static BooleanExpression matches(String fieldName, String rquery) {
@@ -3455,7 +3475,7 @@ static BooleanExpression matches(String fieldName, String rquery) {
    * <p>This Expression can only be used within a {@code Search} stage.
    *
    * @param field Perform search on this field.
-   * @param rquery Define the search query using the rquery DTS.
+   * @param rquery Define the search query using the search DSL.
    */
   @InternalApi
   static BooleanExpression matches(Field field, String rquery) {
@@ -3464,10 +3484,18 @@ static BooleanExpression matches(Field field, String rquery) {
 
   /**
    * Evaluates to the search score that reflects the topicality of the document to all of the text
-   * predicates ({@code matches} and {@code documentMatches}) in the search query.
+   * predicates (for example: {@code documentMatches}) in the search query.
    *
    * <p>This Expression can only be used within a {@code Search} stage.
    *
+   * <p>Example:
+   *
+   * <pre>{@code
+   * db.pipeline().collection("restaurants").search(
+   *   Search.withQuery("waffles").withSort(score().descending())
+   * )
+   * }</pre>
+   *
    * @return A new {@link Expression} representing the score operation.
    */
   @BetaApi
@@ -3481,8 +3509,16 @@ public static Expression score() {
    *
    * <p>This Expression can only be used within a {@code Search} stage.
    *
+   * <p>Example:
+   *
+   * <pre>{@code
+   * db.pipeline().collection("restaurants").search(
+   *   Search.withQuery("waffles").withAddFields(snippet("menu", "waffles").as("snippet"))
+   * )
+   * }</pre>
+   *
    * @param fieldName Search the specified field for matching terms.
-   * @param rquery Define the search query using the search DTS.
+   * @param rquery Define the search query using the search DSL.
    * @return A new {@link Expression} representing the snippet operation.
    */
   @BetaApi
@@ -3497,7 +3533,15 @@ public static Expression snippet(String fieldName, String rquery) {
    *
    * <p>This Expression can only be used within a {@code Search} stage.
    *
-   * @param rquery Define the search query using the search DTS.
+   * <p>Example:
+   *
+   * <pre>{@code
+   * db.pipeline().collection("restaurants").search(
+   *   Search.withQuery("waffles").withAddFields(field("menu").snippet("waffles").as("snippet"))
+   * )
+   * }</pre>
+   *
+   * @param rquery Define the search query using the search DSL.
    * @return A new {@link Expression} representing the snippet operation.
    */
   @BetaApi

google-cloud-firestore/src/main/java/com/google/cloud/firestore/pipeline/stages/Search.java

@@ -37,6 +37,16 @@
  * The Search stage executes full-text search or geo search operations.
  *
  * <p>The Search stage must be the first stage in a Pipeline.
+ *
+ * <p>Example:
+ *
+ * <pre>{@code
+ * db.pipeline().collection("restaurants").search(
+ *   Search.withQuery(documentMatches("waffles OR pancakes"))
+ *     .withSort(score().descending())
+ *     .withLimit(10)
+ * );
+ * }</pre>
  */
 @BetaApi
 public final class Search extends Stage {
@@ -141,8 +151,8 @@ public Search withLimit(long limit) {
   }
 
   /**
-   * Specify the maximum number of documents for the search stage to score. Documents will be
-   * processed in the pre-sort order specified by the search index.
+   * Specify the maximum number of documents to retrieve. Documents will be retrieved in the
+   * pre-sort order specified by the search index.
    */
   public Search withRetrievalDepth(long retrievalDepth) {
     return new Search(options.with("retrieval_depth", encodeValue(retrievalDepth)));