datastore query docs don't use datastore.Query shortcuts

[jgeewax]

See http://googlecloudplatform.github.io/gcloud-python/latest/datastore-queries.html#gcloud.datastore.query.Query.fetch

The snippet is

>>> from gcloud.datastore.query import Query
>>> query = Query('dataset-id', 'Person')
>>> query.add_filter('name', '=', 'Sally')
>>> list(query.fetch())
[<Entity object>, <Entity object>, ...]
>>> list(query.fetch(1))
[<Entity object>]

I'd expect it to be

>>> from gcloud import datastore
>>> query = datastore.Query('Person') # note no dataset id
>>> query.add_filter('name', '=', 'Sally')
>>> list(query.fetch())
[<Entity object>, <Entity object>, ...]
>>> list(query.fetch(1))
[<Entity object>]

and a separate example for a specific dataset

>>> from gcloud import datastore
>>> dataset = datastore.Dataset('dataset-id')
>>> query = dataset.Query('Person')
>>> query.add_filter('name', '=', 'Sally')
>>> list(query.fetch())
[<Entity object>, <Entity object>, ...]
>>> list(query.fetch(1))
[<Entity object>]

[dhermes]

@jgeewax Three salient things here:

• The dataset_id and kind args should be swapped in the Query constructor
• These docs come from the class itself, hence the fully qualified import.
• The Dataset docs should cover how to make a query from a dataset, not here. We can beef up the docstrings in the dataset module though. The only issue is bit rotting as code changes in the source of truth (as you are pointing out).

[dhermes]

@jgeewax #718 deals with swapping the args and the query = datastore.Query('Person') # note no dataset id part, as well as the qualified import.

It doesn't deal with Dataset docs.

[dhermes]

Closing this since #750 covers the last remaining piece.