From 6b3464605bb26f750a29dece14475fcb87a926d1 Mon Sep 17 00:00:00 2001
From: Sebastian Schmidt <mrschmidt@google.com>
Date: Tue, 21 Dec 2021 10:15:11 -0700
Subject: [PATCH] docs: add @throws API comment for CRUD methods

---
 packages/firestore/src/lite-api/reference_impl.ts | 5 +++++
 packages/firestore/src/lite-api/transaction.ts    | 4 ++++
 packages/firestore/src/lite-api/write_batch.ts    | 3 +++
 3 files changed, 12 insertions(+)

diff --git a/packages/firestore/src/lite-api/reference_impl.ts b/packages/firestore/src/lite-api/reference_impl.ts
index 5bb527d1236..d7ec2c62655 100644
--- a/packages/firestore/src/lite-api/reference_impl.ts
+++ b/packages/firestore/src/lite-api/reference_impl.ts
@@ -194,6 +194,7 @@ export function getDocs<T>(query: Query<T>): Promise<QuerySnapshot<T>> {
  *
  * @param reference - A reference to the document to write.
  * @param data - A map of the fields and values for the document.
+ * @throws Error - If the provided input is not a valid Firestore document.
  * @returns A `Promise` resolved once the data has been successfully written
  * to the backend.
  */
@@ -214,6 +215,7 @@ export function setDoc<T>(
  * @param reference - A reference to the document to write.
  * @param data - A map of the fields and values for the document.
  * @param options - An object to configure the set behavior.
+ * @throws Error - If the provided input is not a valid Firestore document.
  * @returns A `Promise` resolved once the data has been successfully written
  * to the backend.
  */
@@ -263,6 +265,7 @@ export function setDoc<T>(
  * @param data - An object containing the fields and values with which to
  * update the document. Fields can contain dots to reference nested fields
  * within the document.
+ * @throws Error - If the provided input is not valid Firestore data.
  * @returns A `Promise` resolved once the data has been successfully written
  * to the backend.
  */
@@ -287,6 +290,7 @@ export function updateDoc<T>(
  * @param field - The first field to update.
  * @param value - The first value.
  * @param moreFieldsAndValues - Additional key value pairs.
+ * @throws Error - If the provided input is not valid Firestore data.
  * @returns A `Promise` resolved once the data has been successfully written
  * to the backend.
  */
@@ -370,6 +374,7 @@ export function deleteDoc(
  *
  * @param reference - A reference to the collection to add this document to.
  * @param data - An Object containing the data for the new document.
+ * @throws Error - If the provided input is not a valid Firestore document.
  * @returns A `Promise` resolved with a `DocumentReference` pointing to the
  * newly created document after it has been written to the backend.
  */
diff --git a/packages/firestore/src/lite-api/transaction.ts b/packages/firestore/src/lite-api/transaction.ts
index aadba43dc63..38297e8528f 100644
--- a/packages/firestore/src/lite-api/transaction.ts
+++ b/packages/firestore/src/lite-api/transaction.ts
@@ -118,6 +118,7 @@ export class Transaction {
    *
    * @param documentRef - A reference to the document to be set.
    * @param data - An object of the fields and values for the document.
+   * @throws Error - If the provided input is not a valid Firestore document.
    * @returns This `Transaction` instance. Used for chaining method calls.
    */
   set<T>(documentRef: DocumentReference<T>, data: WithFieldValue<T>): this;
@@ -130,6 +131,7 @@ export class Transaction {
    * @param documentRef - A reference to the document to be set.
    * @param data - An object of the fields and values for the document.
    * @param options - An object to configure the set behavior.
+   * @throws Error - If the provided input is not a valid Firestore document.
    * @returns This `Transaction` instance. Used for chaining method calls.
    */
   set<T>(
@@ -169,6 +171,7 @@ export class Transaction {
    * @param data - An object containing the fields and values with which to
    * update the document. Fields can contain dots to reference nested fields
    * within the document.
+   * @throws Error - If the provided input is not valid Firestore data.
    * @returns This `Transaction` instance. Used for chaining method calls.
    */
   update<T>(documentRef: DocumentReference<T>, data: UpdateData<T>): this;
@@ -184,6 +187,7 @@ export class Transaction {
    * @param field - The first field to update.
    * @param value - The first value.
    * @param moreFieldsAndValues - Additional key/value pairs.
+   * @throws Error - If the provided input is not valid Firestore data.
    * @returns This `Transaction` instance. Used for chaining method calls.
    */
   update(
diff --git a/packages/firestore/src/lite-api/write_batch.ts b/packages/firestore/src/lite-api/write_batch.ts
index eaf97332a1c..e626646f3f7 100644
--- a/packages/firestore/src/lite-api/write_batch.ts
+++ b/packages/firestore/src/lite-api/write_batch.ts
@@ -86,6 +86,7 @@ export class WriteBatch {
    * @param documentRef - A reference to the document to be set.
    * @param data - An object of the fields and values for the document.
    * @param options - An object to configure the set behavior.
+   * @throws Error - If the provided input is not a valid Firestore document.
    * @returns This `WriteBatch` instance. Used for chaining method calls.
    */
   set<T>(
@@ -127,6 +128,7 @@ export class WriteBatch {
    * @param data - An object containing the fields and values with which to
    * update the document. Fields can contain dots to reference nested fields
    * within the document.
+   * @throws Error - If the provided input is not valid Firestore data.
    * @returns This `WriteBatch` instance. Used for chaining method calls.
    */
   update<T>(documentRef: DocumentReference<T>, data: UpdateData<T>): WriteBatch;
@@ -142,6 +144,7 @@ export class WriteBatch {
    * @param field - The first field to update.
    * @param value - The first value.
    * @param moreFieldsAndValues - Additional key value pairs.
+   * @throws Error - If the provided input is not valid Firestore data.
    * @returns This `WriteBatch` instance. Used for chaining method calls.
    */
   update(