docs(firestore): clarify update/upsert target path Javadoc and Upsert sample

Author: dlarocque

java-firestore/google-cloud-firestore/src/main/java/com/google/cloud/firestore/Pipeline.java

@@ -1225,13 +1225,13 @@ public Pipeline delete() {
   /**
    * Performs an update operation using documents from previous stages.
    *
-   * <p>This method updates the documents in place based on the data flowing through the pipeline.
-   * To specify transformations, use {@link #update(Selectable...)}.
+   * <p>This method updates existing documents based on the data flowing through the pipeline. To
+   * specify transformations, use {@link #update(Selectable...)}.
    *
-   * <p>Each document is written back to its existing path. The stored document is replaced by the
-   * pipeline document, so fields removed by earlier stages (for example, with {@link
-   * #removeFields(String, String...)}) are also removed from the stored document. This stage does
-   * not create documents: documents that don't exist are skipped.
+   * <p>Each document is written to the path given by its {@code __name__} field. The stored
+   * document is replaced by the pipeline document, so fields removed by earlier stages (for
+   * example, with {@link #removeFields(String, String...)}) are also removed from the stored
+   * document. This stage does not create documents: target documents that don't exist are skipped.
    *
    * <p>Example 1: Update a collection's schema by adding a new field and removing an old one.
    *
@@ -1245,7 +1245,7 @@ public Pipeline delete() {
    *     .get();
    * }</pre>
    *
-   * <p>Example 2: Update documents in place with data from literals.
+   * <p>Example 2: Update documents with data from literals.
    *
    * <pre>{@code
    * Map<String, Object> updateData = new HashMap<>();
@@ -1381,10 +1381,10 @@ public Pipeline upsert(Upsert upsert) {
   }
 
   /**
-   * Writes each document produced by the previous stages back to its own path, after adding the
-   * given fields. The document is created if it doesn't exist and replaced if it does; stored
-   * fields are not merged. A document without a {@code __name__} field fails with {@code
-   * INVALID_ARGUMENT}.
+   * Writes each document produced by the previous stages to the path given by its {@code __name__}
+   * field, after adding the given fields. The document is created if it doesn't exist and replaced
+   * if it does; stored fields are not merged. A document without a {@code __name__} field fails
+   * with {@code INVALID_ARGUMENT}.
    *
    * <p>Example:
    *

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

@@ -27,7 +27,9 @@
 import javax.annotation.Nullable;
 
 /**
- * A pipeline stage that updates, in place, the documents produced by the previous stages.
+ * A pipeline stage that updates existing documents in the database using the documents produced by
+ * the previous stages. Each input document's {@code __name__} field identifies the target document
+ * to update.
  *
  * <p>Use with {@link com.google.cloud.firestore.Pipeline#update(Update)}, or call {@link
  * com.google.cloud.firestore.Pipeline#update()} / {@link

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

@@ -49,11 +49,12 @@
  * <p>Example:
  *
  * <pre>{@code
- * // Set "status" on each matching document and write it back to its own path.
+ * // Set "status" on each matching document and write it to the path given by its __name__ field.
  * firestore.pipeline()
  *     .collection("books")
  *     .where(field("rating").greaterThan(4))
- *     .upsert(new Upsert().withAdditionalFields(constant("Featured").as("status")))
+ *     .addFields(constant("Featured").as("status"))
+ *     .upsert()
  *     .execute()
  *     .get();
  * }</pre>
@@ -79,15 +80,15 @@ private Upsert(
 
   /**
    * Creates an upsert stage with no additional fields, no target collection and no document ID
-   * expression, so each document is written back to its own path.
+   * expression, so each document is written to the path given by its {@code __name__} field.
    */
   public Upsert() {
     this((ImmutableList<Selectable>) null, null, null, InternalOptions.EMPTY);
   }
 
   /**
    * Creates an upsert stage that adds the given fields to each input document before it is written
-   * back to its own path.
+   * to the path given by its {@code __name__} field.
    *
    * @param additionalFields Fields to add to each input document. A field with the same name as an
    *     existing input field overwrites that field.