Clean up rxfire API documentation (#2584)

* Fixed markdown so parameters are visible in displayed tables for each function.

* Updated function descriptions.

* Updated examples.

Author: shelcindra

packages/rxfire/docs/firestore.md

@@ -1,14 +1,13 @@
 # RxFire Firestore
 
-## Document Observables
 
 ### `doc()`
-The `doc()` function creates an observable that emits document changes.
+The `doc()` function creates an observable that emits document changes.  Returns snapshot of the data each time the document changes.
 
 |                 |                                          |
 |-----------------|------------------------------------------|
 | **function**    | `doc()`                                  |
-| **params**      | `firestore.DocumentReference`            |
+| **params**      | `ref:firestore.DocumentReference`        |
 | **import path** | `rxfire/firestore`                       |
 | **return**      | `Observable<firestore.DocumentSnapshot>` |
 
@@ -17,24 +16,23 @@ The `doc()` function creates an observable that emits document changes.
 import { doc } from 'rxfire/firestore';
 import { firestore, initializeApp } from 'firebase';
 import 'firebase/firestore';
-import { map } from 'rxjs/operators';
 
 // Set up Firebase
 const app = initializeApp({ /* config */ });
 const db = app.firestore();
-const davidDoc = db.doc('users/david');
+const davidDocRef = db.doc('users/david');
 
 // Seed the firestore
-davidDoc.set({ name: 'David' });
+davidDocRef.set({ name: 'David' });
 
-doc(davidDoc).subscribe(snapshot => {
+doc(davidDocRef).subscribe(snapshot => {
   console.log(snapshot.id);
   console.log(snapshot.data());
 });
 ```
 
 ### `docData()`
-The `docData()` function returns a stream of a document, mapped to its data payload and optionally the document ID.
+The `docData()` function creates an observable that returns a stream of a document, mapped to its data field values and, optionally, the document ID.
 
 |                 |                                          |
 |-----------------|------------------------------------------|
@@ -65,12 +63,12 @@ docData(davidDocRef,'uid').subscribe(userData => {
 ## Collection Observables
 
 ### `collection()`
-The `collection()` function creates an observable that emits collection changes.
+The `collection()` function creates an observable that emits changes to the specified collection based on the input query.  Any time updates are made, the function returns all documents in the collection that match the query.
 
 |                 |                                          |
 |-----------------|------------------------------------------|
 | **function**    | `collection()`                           |
-| **params**      | `firestore.CollectionReference` | `firestore.Query` |
+| **params**      | query: `firestore.CollectionReference | firestore.Query` |
 | **import path** | `rxfire/firestore`                       |
 | **return**      | `Observable<firestore.QueryDocumentSnapshot[]>`    |
 
@@ -79,28 +77,24 @@ The `collection()` function creates an observable that emits collection changes.
 import { collection } from 'rxfire/firestore';
 import { firestore, initializeApp } from 'firebase';
 import 'firebase/firestore';
-import { map } from 'rxjs/operators';
 
 // Set up Firebase
 const app = initializeApp({ /* config */ });
 const db = app.firestore();
-const davidDoc = db.doc('users/david');
+const collectionRef = db.collection('users');
 
-// Seed the firestore
-davidDoc.set({ name: 'David' });
-
-collection(db.collection('users'))
+collection(collectionRef)
   .pipe(map(docs => docs.map(d => d.data())))
   .subscribe(users => { console.log(users) });
 ```
 
 ### `collectionData()`
-The `collectionData()` function creates an observable that emits a stream of collection documents payload with optional document ID.
+The `collectionData()` function creates an observable that emits a stream of documents for the specified collection based on the input query.  When updates are made, returns all documents (field values and optional document ID) in the collection that match the query.
 
 |                 |                                          |
 |-----------------|------------------------------------------|
-| **function**    | `collection()`                           |
-| **params**      | query: `firestore.CollectionReference` | `firestore.Query`, idField?: `string`  |
+| **function**    | `collectionData()`                           |
+| **params**      | query: `firestore.CollectionReference | firestore.Query` <br> idField?: `string`  |
 | **import path** | `rxfire/firestore`                       |
 | **return**      | `Observable<T[]>`    |
 
@@ -113,22 +107,19 @@ import 'firebase/firestore';
 // Set up Firebase
 const app = initializeApp({ /* config */ });
 const db = app.firestore();
-const davidDoc = db.doc('users/david');
+const collectionRef = db.collection('users');
 
-// Seed the firestore
-davidDoc.set({ name: 'David' });
-
-collectionData(db.collection('users'), 'uid')
+collectionData(collectionRef, 'uid')
   .subscribe(users => { console.log(users) });
 ```
 
 ### `collectionChanges()`
-The `collectionChanges()` function creates an observable that emits the event changes on a collection. This is different than the collection function in that it does not contain the state of your application but only the individual changes. The optional `events` parameter will filter which child events populate the array.
+The `collectionChanges()` function creates an observable that emits the changes on the specified collection based on the input query. This is different than the collection function in that it does not contain the state of your application but only the individual changes. The optional `events` parameter filters which the type of change populate the array. By default, all changes are emitted. Returns the affected documents and the type of change that occurred (added, modified, or removed).
 
 |                 |                                          |
 |-----------------|------------------------------------------|
 | **function**    | `collectionChanges()`                           |
-| **params**      | query: `firestore.CollectionReference` | `firestore.Query`, events?: `firestore.DocumentChangeType[]` |
+| **params**      | query: `firestore.CollectionReference | firestore.Query` <br> events?: `firestore.DocumentChangeType[]` |
 | **import path** | `rxfire/firestore`                       |
 | **return**      | `Observable<firestore.DocumentChange[]>`    |
 
@@ -142,16 +133,14 @@ import { map } from 'rxjs/operators';
 // Set up Firebase
 const app = initializeApp({ /* config */ });
 const db = app.firestore();
-const davidDoc = db.doc('users/david');
-
-// Seed the firestore
-davidDoc.set({ name: 'David' });
+const collectionRef = db.collection('users');
 
-collectionChanges(db.collection('users'))
-  .subscribe(changes => { console.log(users) });
+// Listen to all events
+collectionChanges(collectionRef)
+  .subscribe(changes => { console.log(changes) });
 
 // Listen to only 'added' events
-collectionChanges(db.collection('users'), ['added'])
+collectionChanges(collectionRef, ['added'])
   .subscribe(addedEvents => { console.log(addedEvents) });
 ```
 
@@ -161,7 +150,7 @@ The `sortedChanges()` function creates an observable that emits the reduced stat
 |                 |                                          |
 |-----------------|------------------------------------------|
 | **function**    | `sortedChanges()`                           |
-| **params**      | query: `firestore.CollectionReference` | `firestore.Query`, events?: `firestore.DocumentChangeType[]` |
+| **params**      | query: `firestore.CollectionReference | firestore.Query`<br> events?: `firestore.DocumentChangeType[]` |
 | **import path** | `rxfire/firestore`                       |
 | **return**      | `Observable<firestore.DocumentChange[]>`    |
 
@@ -175,26 +164,24 @@ import { map } from 'rxjs/operators';
 // Set up Firebase
 const app = initializeApp({ /* config */ });
 const db = app.firestore();
-const davidDoc = db.doc('users/david');
+const collectionRef = db.collection('users');
 
-// Seed the firestore
-davidDoc.set({ name: 'David' });
-
-sortedChanges(db.collection('users'))
-  .subscribe(changes => { console.log(users) });
+// Listen to all events
+sortedChanges(collectionRef)
+  .subscribe(changes => { console.log(changes) });
 
 // Listen to only 'added' events
-docChanges(db.collection('users'), ['added'])
+docChanges(collectionRef, ['added'])
   .subscribe(addedEvents => { console.log(addedEvents) });
 ```
 
 ### `auditTrail()`
-The `auditTrail()` function creates an observable that emits the entire state trail. This is useful for debugging or replaying the state of a list in your app. The optional `events` parameter will filter which child events populate the array.
+The `auditTrail()` function creates an observable that emits the entire state trail on the specified collection based on the input query. This is useful for debugging or replaying the changes to the database. The optional `events` parameter filters which the type of change populate the array. By default, all changes are emitted.
 
 |                 |                                                      |
 |-----------------|------------------------------------------------------|
 | **function**    | `auditTrail()`                                       |
-| **params**      | ref: `firestore.Reference` or `firestore.Query`, events?: `firestore.DocumentChangeType[]` |
+| **params**      | ref: `firestore.Reference | firestore.Query`<br> events?: `firestore.DocumentChangeType[]` |
 | **import path** | `rxfire/firestore`                                    |
 | **return**      | `Observable<firestore.DocumentChange[]>`              |
 
@@ -208,39 +195,40 @@ import { map } from 'rxjs/operators';
 // Set up Firebase
 const app = initializeApp({ /* config */ });
 const db = app.firestore();
-const collection = db.collection('users');
-
-// Seed Firestore
-const davidDoc = collection.doc('users/david');
-davidDoc.set({ name: 'David' });
+const collectionRef = db.collection('users');
+const davidDocRef = collectionRef.doc('david');
 
-auditTrail(collection).pipe(
+// Start the audit trail
+auditTrail(collectionRef).pipe(
   map(change => {
     return { 
       _key: change.snapshot.key, 
       event: change.event,
-      ...change.snapshot.val(); 
+      ...change.snapshot.val() 
     };
   })
 ).subscribe(stateTrail => {
   console.log(stateTrail); 
-  /**
-  first emission:
+});
+
+// Seed Firestore
+davidDocRef.set({ name: 'David' });
+
+// Remove the document
+davidDocRef.delete();
+
+/**
+  First emission:
     [{ _key: '3qtWqaKga8jA; name: 'David', event: 'added' }]
   
-  second emission:
+  When more events occur, the trail still contains the previous events.
+
+  Second emission:
     [
       { _key: '3qtWqaKga8jA; name: 'David', event: 'added' },
       { _key: '3qtWqaKga8jA; name: 'David', event: 'removed' } 
     ]
   */
-});
-
-// When more events occur the trail still contains the previous events
-// In this case we'll remove the only item
-davidDoc.delete();
-
-// Now this will trigger the subscribe function above
 ```
 
 ## Event Observables
@@ -251,7 +239,7 @@ The `fromDocRef()` function creates an observable that emits document changes. T
 |                 |                                          |
 |-----------------|------------------------------------------|
 | **function**    | `fromDocRef()`                           |
-| **params**      | ref: `firestore.Reference`               |
+| **params**      |  ref: `firestore.DocumentReference` <br> options?: `firestore.SnapshotListenOptions`              |
 | **import path** | `rxfire/firestore`                       |
 | **return**      | `Observable<firestore.DocumentSnapshot>` |
 
@@ -265,21 +253,21 @@ import { map } from 'rxjs/operators';
 // Set up Firebase
 const app = initializeApp({ /* config */ });
 const db = app.firestore();
-const davidDoc = db.doc('users/david');
+const davidDocRef = db.doc('users/david');
 
 // Seed Firestore
-davidDoc.set({ name: 'David' });
+davidDocRef.set({ name: 'David' });
 
-fromDocRef(davidDoc).subscribe(snap => { console.log(snap); })
+fromDocRef(davidDocRef).subscribe(snap => { console.log(snap); })
 ```
 
 ### `fromCollectionRef()`
-The `fromCollectionRef()` function creates an observable that emits document changes. This is different than the `collection()` function in that it returns the full `QuerySnapshot` instead of plucking off the `QueryDocumentSnapshot[]` array.
+The `fromCollectionRef()` function creates an observable that emits changes to the specified collection based on the input query and, optionally, the listen options. This is different than the `collection()` function in that it returns the full `QuerySnapshot` representing the results of the query.
 
 |                 |                                          |
 |-----------------|------------------------------------------|
 | **function**    | `fromCollectionRef()`                    |
-| **params**      | ref: `firestore.CollectionReference` or `firestore.Query` |
+| **params**      | ref: `firestore.Reference | firestore.Query`<br> options?: `firestore.SnapshotListenOptions` |
 | **import path** | `rxfire/firestore`                       |
 | **return**      | `Observable<firestore.QuerySnapshot>`    |
 
@@ -293,11 +281,7 @@ import { map } from 'rxjs/operators';
 // Set up Firebase
 const app = initializeApp({ /* config */ });
 const db = app.firestore();
-const collection = db.collection('users');
-const davidDoc = collection.doc('david');
-
-// Seed Firestore
-davidDoc.set({ name: 'David' });
+const collectionRef = db.collection('users');
 
-fromCollectionRef(collection).subscribe(snap => { console.log(snap.docs); })
+fromCollectionRef(collectionRef).subscribe(snap => { console.log(snap.docs); })
 ```