Firestore: Clarify documentation for '{Document,Collection}.on_snapshot'.

[billyrrr]

on_snapshot defined in DocumentReference documentation is inconsistent with those of Watch and Product Documentation.

In DocumentReference documentation, we have

google-cloud-python/firestore/google/cloud/firestore_v1/document.py

Lines 503 to 504 in f890d29

	callback(Callable[[:class:`~google.cloud.firestore.document.DocumentSnapshot`], NoneType]):
	a callback to run when a change occurs

and

google-cloud-python/firestore/google/cloud/firestore_v1/document.py

Lines 515 to 517 in f890d29

	def on_snapshot(document_snapshot):
	doc = document_snapshot
	print(u'{} => {}'.format(doc.id, doc.to_dict()))

In Watch documentation, we have

google-cloud-python/firestore/google/cloud/firestore_v1/watch.py

Lines 183 to 191 in f890d29

	snapshot_callback: Callback method to process snapshots.
	Args:
	docs (List(DocumentSnapshot)): A callback that returns the
	ordered list of documents stored in this snapshot.
	changes (List(str)): A callback that returns the list of
	changed documents since the last snapshot delivered for
	this watch.
	read_time (string): The ISO 8601 time at which this
	snapshot was obtained.

In Product Documentation, we have

# Create a callback on_snapshot function to capture changes
def on_snapshot(doc_snapshot, changes, read_time):
    for doc in doc_snapshot:
        print(u'Received document snapshot: {}'.format(doc.id))

doc_ref = db.collection(u'cities').document(u'SF')

# Watch the document
doc_watch = doc_ref.on_snapshot(on_snapshot)

The function signature in DocumentReference takes 1 argument, but the function signature in Watch and Product Documentation takes 3 arguments. Are these referring to the same function? If so, the documentation in DocumentReference may be updated to reflect these changes. If not, on_snapshot in Product Documentation may be renamed to a different name than on_snapshot in DocumentReference to be more clear.

Will probably submit a pull request to update documentation in DocumentReference to be consistent with that in Watch.

Thanks!

[tseaver]

@billyrrr Thanks for the report. The example for Query.on_snapshot is correct:

google-cloud-python/firestore/google/cloud/firestore_v1/query.py

Lines 804 to 806 in e993961

	def on_snapshot(docs, changes, read_time):
	for doc in docs:
	print(u'{} => {}'.format(doc.id, doc.to_dict()))

while Document.on_snapshot and Collection.on_snapshot show invalid uses. All three need to update the callback argument specification to show the three arguments.