datastore: update docs to show how to get the Key (#1725)

packages/datastore/README.md

@@ -55,7 +55,7 @@ datastore.save({
   key: blogPostKey,
   data: blogPostData
 }).then(function() {
-  // The blog post is not published!
+  // The blog post is now published!
 });
 
 // It's also possible to integrate with third-party Promise libraries.

packages/datastore/src/index.js

@@ -107,8 +107,8 @@ var Transaction = require('./transaction.js');
  * var key = datastore.key(['Company', 'Google']);
  *
  * datastore.get(key, function(err, entity) {
- *   // entity.data = The record.
- *   // entity.key = The key.
+ *   // entity = The record.
+ *   // entity[datastore.KEY] = The key for this entity.
  * });
  *
  * //-
@@ -147,13 +147,10 @@ var Transaction = require('./transaction.js');
  * // Run the query with {module:datastore#runQuery}.
  * //-
  * datastore.runQuery(query, function(err, entities) {
- *   // entities = [
- *   //   {
- *   //     data: The record,
- *   //     key: The key for this record
- *   //   },
- *   //   ...
- *   // ]
+ *   // entities = An array of records.
+ *
+ *   // Access the Key object for an entity.
+ *   var firstEntityKey = entities[0][datastore.KEY];
  * });
  *
  * //-
@@ -227,11 +224,8 @@ var Transaction = require('./transaction.js');
  * //-
  * datastore.get(key, function(err, entity) {
  *   // entity = {
- *   //   key: datastore.key(['Company', 'Google']),
- *   //   data: {
- *   //     name: 'Google',
- *   //     location: 'CA'
- *   //   }
+ *   //   name: 'Google',
+ *   //   location: 'CA'
  *   // }
  * });
  *
@@ -280,16 +274,16 @@ var Transaction = require('./transaction.js');
  *
  *   var key = datastore.key(['Company', 'Google']);
  *
- *   transaction.get(key, function(err, data) {
+ *   transaction.get(key, function(err, entity) {
  *     if (err) {
  *       // Error handling omitted.
  *     }
  *
- *     data.symbol = 'GOOG';
+ *     entity.symbol = 'GOOG';
  *
  *     transaction.save({
  *       key: key,
- *       data: data
+ *       data: entity
  *     });
  *
  *     transaction.commit(function(err) {

packages/datastore/src/query.js

@@ -293,7 +293,12 @@ Query.prototype.offset = function(n) {
  *     - {module:datastore#NO_MORE_RESULTS}: There are no more results.
  *
  * @example
- * query.run(function(err, entities, info) {});
+ * query.run(function(err, entities, info) {
+ *   // entities = An array of records.
+ *
+ *   // Access the Key object for an entity.
+ *   var firstEntityKey = entities[0][datastore.KEY];
+ * });
  *
  * //-
  * // A keys-only query returns just the keys of the result entities instead of
@@ -331,7 +336,10 @@ Query.prototype.run = function() {
  * @example
  * query.runStream()
  *   .on('error', console.error)
- *   .on('data', function (entity) {})
+ *   .on('data', function (entity) {
+ *     // Access the Key object for this entity.
+ *     var key = entity[datastore.KEY];
+ *   })
  *   .on('info', function(info) {})
  *   .on('end', function() {
  *     // All entities retrieved.

packages/datastore/src/request.js

@@ -466,7 +466,12 @@ DatastoreRequest.prototype.insert = function(entities, callback) {
  * //-
  * var query = datastore.createQuery('Lion');
  *
- * datastore.runQuery(query, function(err, entities, info) {});
+ * datastore.runQuery(query, function(err, entities, info) {
+ *   // entities = An array of records.
+ *
+ *   // Access the Key object for an entity.
+ *   var firstEntityKey = entities[0][datastore.KEY];
+ * });
  *
  * //-
  * // Or, if you're using a transaction object.
@@ -541,7 +546,10 @@ DatastoreRequest.prototype.runQuery = function(query, options, callback) {
  * @example
  * datastore.runQueryStream(query)
  *   .on('error', console.error)
- *   .on('data', function (entity) {})
+ *   .on('data', function(entity) {
+ *     // Access the Key object for this entity.
+ *     var key = entity[datastore.KEY];
+ *   })
  *   .on('info', function(info) {})
  *   .on('end', function() {
  *     // All entities retrieved.
@@ -552,7 +560,7 @@ DatastoreRequest.prototype.runQuery = function(query, options, callback) {
  * // unnecessary processing and API requests.
  * //-
  * datastore.runQueryStream(query)
- *   .on('data', function (entity) {
+ *   .on('data', function(entity) {
  *     this.end();
  *   });
  */

packages/datastore/src/transaction.js

@@ -348,12 +348,12 @@ Transaction.prototype.rollback = function(callback) {
  *   // Perform Datastore transactional operations.
  *   var key = datastore.key(['Company', 123]);
  *
- *   transaction.get(key, function(err, data) {
- *     data.name = 'Google';
+ *   transaction.get(key, function(err, entity) {
+ *     entity.name = 'Google';
  *
  *     transaction.save({
  *       key: key,
- *       data: data
+ *       data: entity
  *     });
  *
  *     transaction.commit(function(err) {