[Docs] Indicate create*Query options.results is a Doc[]

[ericyhwang]

The Connection's createFetchQuery and createSubscribeQuery take an optional existing result array as options.results.

It should be an array of Doc instances:

sharedb/lib/client/connection.js

Lines 563 to 567 in 1cca122

	// If present, the callback should have the signature function(error, results, extra)
	// where results is a list of Doc objects.
	Connection.prototype.createSubscribeQuery = function(collection, q, options, callback) {
	return this._createQuery('qs', collection, q, options, callback);
	};

This PR updates the docs to indicate the specific type, instead of Object[].

[coveralls]

Coverage decreased (-97.4%) to 0.0% when pulling c49ad21 on docs-createQuery-options-types into 1cca122 on master.

[curran]

LGTM!

[curran]

Very nice! It might help to explicitly state in the docs what is expected with regards to subscription status.

[alecgibson]

I agree — might be nice to expand on how to actually get this Doc array (I have to admit I've never done this, so when I wrote the documentation, I didn't add any details)

[curran]

Cool! I'm (hopefully) going to be experimenting with this API soon, so I can test out what happens in the various cases and report back / update the docs when I do:

• Doc not fetched or subscribed
• Doc fetched but not subscribed
• Doc fetched and subscribed

[curran]

I have verified the behavior for the various cases.

Short answer: any combination of fetch and subscribe states appears to work, as long as each doc in results is initialized using connection.get.

Long answer:

• If the docs in results are initialized with connection.get followed by ingestSnapshot (without subscribing), then the query implementation will subscribe to all of them (note that you still need to manually add the listeners for doc.on('load') and doc.on('op') - the subscribeQuery does not fire events when the individual docs are updated, only when the query result list is changed). In this case, we get a message that looks like this over WebSockets a: [["id1", 10], ["id2", 3],.... This does not contain the full documents, only their ids and versions, which is the expected behavior here. Awesome!
• If the docs in results are initialized with only connection.get and nothing else, then a message appears overWebSockets that contains the full document contents for each individual doc.

[curran]

Closes #501

(just commenting so we can easily find this PR from the issue)

[curran]

Added suggestions that add more detail around expected state of the Doc instances.