Include overview documentation on all API pages, and talk about Promises/Callbacks

[quentin-sommer]

Environment details

• OS: linux
• Node.js version: 7.7.3
• npm version: 4.4.4
• google-cloud-node version: @google-cloud/datastore: 0.7.1

Steps to reproduce

1. require @google-cloud/datastore
2. get(keyObj)

Using a callback approach with 1 key
get(key, (err, entity) => {} will output an object

whereas using a promise approach with 1 key
get(key).then(entity => {}) will output a 1 sized array containing the object

[stephenplusplus]

This is true for all of our methods, and that's why we do it-- for the consistency. Most of our methods return multiple arguments. datastore.get() is a rare exception. It's understandably confusing that we're using an array where only one value is expected, but we have to do it so users don't always have to confirm with our docs which methods resolve a promise with an array and which ones don't. Sorry for the confusion.

[gunar]

@stephenplusplus Hi there! A bit of feedback: this is confusing and hard to find an answer for. You should improve docs there.

Moreover, I don't think your answer addresses the question at all. Why doesn't the callback API return an array too then? That would consistent (although weird).

[stephenplusplus]

We have two ways of using every method, and I think if we dual-documented every method, we'd end up confusing everybody. In our documentation, each method has an examples section. If it can be run as a promise, it will show the response arguments to the then handler. That's where we show that an array is returned.

Why doesn't the callback API return an array too then?

We're trying to be consistent for each user. A promise user should expect us to be consistent with how we return responses in promise mode, and a callback user should expect us to be consistent with how we return responses in callback mode. We can't be consistent between callback and promise because of the promise spec, which refuses multiple arguments to a promise's resolution. In other words, we can't do this:

method().then(function(items, apiResponse) {})

We have to do put them into a single structure of either an array or object

method().then(function(resp) { resp[0] === items && resp[1] === apiResponse })

You should improve docs there.

I want this, too. How?

[quentin-sommer]

An introductory paragraph explaining the thing you just explained :) most libraries I've used in node return array for multiple results and objects for single results.

So I jumped to this conclusion and was confused

[callmehiphop]

@stephenplusplus this brings up a good point - if we're deprecating the meta packages, perhaps we'll need to include instructions for things that would have typically belonged inside of the meta package overview everywhere else (e.g. interceptors, promises, config object, etc.)

[stephenplusplus]

Good thinking, maybe it should be part of the Overview template.

[gunar]

I see progress and I see no need for further commenting on my part.
Thank you very much and congrats on thorough feedback process.