docs: add types for docs

dev/src/index.ts

@@ -161,6 +161,53 @@ const MAX_CONCURRENT_REQUESTS_PER_CLIENT = 100;
  * @typedef {Object.<string, *>} DocumentData
  */
 
+/**
+ * Converter used by [withConverter()]{@link Query#withConverter} to transform
+ * user objects of type T into Firestore data.
+ *
+ * Using the converter allows you to specify generic type arguments when storing
+ * and retrieving objects from Firestore.
+ *
+ * @example
+ * class Post {
+ *   constructor(readonly title: string, readonly author: string) {}
+ *
+ *   toString(): string {
+ *     return this.title + ', by ' + this.author;
+ *   }
+ * }
+ *
+ * const postConverter = {
+ *   toFirestore(post: Post): FirebaseFirestore.DocumentData {
+ *     return {title: post.title, author: post.author};
+ *   },
+ *   fromFirestore(
+ *     data: FirebaseFirestore.QueryDocumentSnapshot
+ *   ): Post {
+ *     const data = snapshot.data();
+ *     return new Post(data.title, data.author);
+ *   }
+ * };
+ *
+ * const postSnap = await Firestore()
+ *   .collection('posts')
+ *   .withConverter(postConverter)
+ *   .doc().get();
+ * const post = postSnap.data();
+ * if (post !== undefined) {
+ *   post.title; // string
+ *   post.toString(); // Should be defined
+ *   post.someNonExistentProperty; // TS error
+ * }
+ *
+ * @property {Function} toFirestore Called by the Firestore SDK to convert a
+ * custom model object of type T into a plain Javascript object (suitable for
+ * writing directly to the Firestore database).
+ * @property {Function} fromFirestore Called by the Firestore SDK to convert
+ * Firestore data into an object of type T.
+ * @typedef {Object} FirestoreDataConverter
+ */
+
 /**
  * Update data (for use with [update]{@link DocumentReference#update})
  * that contains paths (e.g. 'foo' or 'foo.baz') mapped to values. Fields that

dev/src/reference.ts

@@ -535,11 +535,10 @@ export class DocumentReference<T = DocumentData> implements Serializable {
   }
 
   /**
-   * Applies a custom data converter to this DocumentReference, allowing you
-   * to use your own custom model objects with Firestore. When you call
-   * set(), get(), etc. on the returned DocumentReference instance, the
-   * provided converter will convert between Firestore data and your custom
-   * type U.
+   * Applies a custom data converter to this DocumentReference, allowing you to
+   * use your own custom model objects with Firestore. When you call set(),
+   * get(), etc. on the returned DocumentReference instance, the provided
+   * converter will convert between Firestore data and your custom type U.
    *
    * Using the converter allows you to specify generic type arguments when
    * storing and retrieving objects from Firestore.
@@ -576,7 +575,8 @@ export class DocumentReference<T = DocumentData> implements Serializable {
    *   post.someNonExistentProperty; // TS error
    * }
    *
-   * @param converter Converts objects to and from Firestore.
+   * @param {FirestoreDataConverter=} converter Converts objects to and from
+   * Firestore.
    * @return A DocumentReference<U> that uses the provided converter.
    */
   withConverter<U>(converter: FirestoreDataConverter<U>): DocumentReference<U> {
@@ -2176,7 +2176,8 @@ export class Query<T = DocumentData> {
    *   post.someNonExistentProperty; // TS error
    * }
    *
-   * @param converter Converts objects to and from Firestore.
+   * @param {FirestoreDataConverter=} converter Converts objects to and from
+   * Firestore.
    * @return A Query<U> that uses the provided converter.
    */
   withConverter<U>(converter: FirestoreDataConverter<U>): Query<U> {
@@ -2411,8 +2412,8 @@ export class CollectionReference<T = DocumentData> extends Query<T> {
 
   /**
    * Applies a custom data converter to this CollectionReference, allowing you
-   * to use your own custom model objects with Firestore. When you call add()
-   * on the returned CollectionReference instance, the provided converter will
+   * to use your own custom model objects with Firestore. When you call add() on
+   * the returned CollectionReference instance, the provided converter will
    * convert between Firestore data and your custom type U.
    *
    * Using the converter allows you to specify generic type arguments when
@@ -2450,7 +2451,8 @@ export class CollectionReference<T = DocumentData> extends Query<T> {
    *   post.someNonExistentProperty; // TS error
    * }
    *
-   * @param converter Converts objects to and from Firestore.
+   * @param {FirestoreDataConverter=} converter Converts objects to and from
+   * Firestore.
    * @return A CollectionReference<U> that uses the provided converter.
    */
   withConverter<U>(