Merge pull request #903 from callmehiphop/docs

Documentation bug fixes

lib/datastore/index.js

@@ -110,6 +110,15 @@ Datastore.dataset = Dataset;
  *     server (usually "http://localhost:8080").
  * @param {string} options.namespace - Namespace to isolate transactions to.
  * @return {module:datastore/dataset}
+ *
+ * @example
+ * var gcloud = require('gcloud')({
+ *   keyFilename: '/path/to/keyfile.json',
+ *   projectId: 'my-project'
+ * });
+ *
+ * var datastore = gcloud.datastore;
+ * var dataset = datastore.dataset();
  */
 Datastore.prototype.dataset = function(options) {
   options = options || {};

lib/datastore/query.js

@@ -75,7 +75,25 @@ function Query(namespace, kinds) {
 }
 
 /**
+ * @param {boolean=} autoPaginateVal - Have pagination handled automatically.
+ *     Default: true.
  * @return {module:datastore/query}
+ *
+ * @example
+ * // Retrieve a list of people related to person "1234",
+ * // disabling auto pagination
+ * var query = dataset.createQuery('Person')
+ *   .hasAncestor(dataset.key(['Person', 1234]))
+ *   .autoPaginate(false);
+ *
+ * var callback = function(err, entities, nextQuery, apiResponse) {
+ *   if (nextQuery) {
+ *     // More results might exist, so we'll manually fetch them
+ *     dataset.runQuery(nextQuery, callback);
+ *   }
+ * };
+ *
+ * dataset.runQuery(query, callback);
  */
 Query.prototype.autoPaginate = function(autoPaginateVal) {
   this.autoPaginateVal = autoPaginateVal !== false;

lib/datastore/request.js

@@ -118,14 +118,15 @@ function DatastoreRequest() {}
  *
  * @example
  * //-
- * // Where you see `transaction`, assume this is the context that's relevant to
- * // your use, whether that be a Dataset or Transaction object.
+ * // Get a single entity.
  * //-
+ * var key = dataset.key(['Company', 123]);
+ *
+ * dataset.get(key, function(err, entity) {});
  *
  * //-
- * // Get a single entity.
+ * // Or, if you're using a transaction object.
  * //-
- * var key = dataset.key(['Company', 123]);
  *
  * transaction.get(key, function(err, entity) {});
  *
@@ -137,12 +138,12 @@ function DatastoreRequest() {}
  *   dataset.key(['Product', 'Computer'])
  * ];
  *
- * transaction.get(keys, function(err, entities) {});
+ * dataset.get(keys, function(err, entities) {});
  *
  * //-
  * // Or, get the entities as a readable object stream.
  * //-
- * transaction.get(keys)
+ * dataset.get(keys)
  *   .on('error', function(err) {})
  *   .on('data', function(entity) {
  *     // entity is an entity object.
@@ -483,16 +484,18 @@ DatastoreRequest.prototype.save = function(entities, callback) {
  * @param {object} callback.apiResponse - The full API response.
  *
  * @example
+ * dataset.delete(dataset.key(['Company', 123]), function(err, apiResp) {});
+ *
  * //-
- * // Where you see `transaction`, assume this is the context that's relevant to
- * // your use case, whether that be a Dataset or a Transaction object.
+ * // Or, if you're using a transaction object.
  * //-
  *
- * // Delete a single entity.
  * transaction.delete(dataset.key(['Company', 123]), function(err, apiResp) {});
  *
+ * //-
  * // Delete multiple entities at once.
- * transaction.delete([
+ * //-
+ * dataset.delete([
  *   dataset.key(['Company', 123]),
  *   dataset.key(['Product', 'Computer'])
  * ], function(err, apiResponse) {});
@@ -555,11 +558,13 @@ DatastoreRequest.prototype.delete = function(keys, callback) {
  * //-
  * var query = dataset.createQuery('Lion');
  *
- * transaction.runQuery(query, function(err, entities) {
- *   if (!err) {
- *     // Handle entities here.
- *   }
- * });
+ * dataset.runQuery(query, function(err, entities) {});
+ *
+ * //-
+ * // Or, if you're using a transaction object.
+ * //-
+ *
+ * transaction.runQuery(query, function(err, entities) {});
  *
  * //-
  * // To control how many API requests are made and page through the results
@@ -574,14 +579,14 @@ DatastoreRequest.prototype.delete = function(keys, callback) {
  *   }
  * };
  *
- * transaction.runQuery(manualPageQuery, callback);
+ * dataset.runQuery(manualPageQuery, callback);
  *
  * //-
  * // If you omit the callback, runQuery will automatically call subsequent
  * // queries until no results remain. Entity objects will be pushed as they are
  * // found.
  * //-
- * transaction.runQuery(query)
+ * dataset.runQuery(query)
  *   .on('error', console.error)
  *   .on('data', function (entity) {})
  *   .on('end', function() {
@@ -594,7 +599,7 @@ DatastoreRequest.prototype.delete = function(keys, callback) {
  * //-
  * var keysOnlyQuery = dataset.createQuery('Lion').select('__key__');
  *
- * transaction.runQuery(keysOnlyQuery, function(err, entities) {
+ * dataset.runQuery(keysOnlyQuery, function(err, entities) {
  *   // entities[].key = Key object
  *   // entities[].data = Empty object
  * });
@@ -644,15 +649,16 @@ DatastoreRequest.prototype.runQuery = function(query, callback) {
  * @param {object} callback.apiResponse - The full API response.
  *
  * @example
- * //-
- * // Where you see `transaction`, assume this is the context that's relevant to
- * // your use, whether that be a Dataset or a Transaction object.
- * //-
- *
  * var incompleteKey = dataset.key(['Company']);
  *
  * // The following call will create 100 new IDs from the Company kind, which
  * // exists under the default namespace.
+ * dataset.allocateIds(incompleteKey, 100, function(err, keys) {});
+ *
+ * //-
+ * // Or, if you're using a transaction object.
+ * //-
+ *
  * transaction.allocateIds(incompleteKey, 100, function(err, keys) {});
  *
  * // You may prefer to create IDs from a non-default namespace by providing an
@@ -664,7 +670,7 @@ DatastoreRequest.prototype.runQuery = function(query, callback) {
  *   path: ['Company']
  * });
  * var callback = function(err, keys, apiResponse) {};
- * transaction.allocateIds(incompleteKey, 100, callback);
+ * dataset.allocateIds(incompleteKey, 100, callback);
  */
 DatastoreRequest.prototype.allocateIds = function(incompleteKey, n, callback) {
   if (entity.isKeyComplete(incompleteKey)) {