Merge pull request #591 from ryanseys/better-ds-save-docs

Add example of using dataset.save with different data types

lib/datastore/request.js

@@ -196,6 +196,76 @@ DatastoreRequest.prototype.insert = function(entities, callback) {
  *   data: {
  *     rating: '10'
  *   }
+ * }, function(err) {
+ *   console.log(key.path); // [ 'Company', 5669468231434240 ]
+ *   console.log(key.namespace); // undefined
+ * });
+ *
+ * //-
+ * // Save a single entity using a provided name instead of auto-generated ID.
+ * //
+ * // Here we are providing a key with name instead of an ID. After saving, the
+ * // original Key object used to save will be updated to contain the path with
+ * // the name instead of a generated ID.
+ * //-
+ * var key = dataset.key(['Company', 'donutshack']);
+ *
+ * dataset.save({
+ *   key: key,
+ *   data: {
+ *     name: 'DonutShack',
+ *     rating: 8
+ *   }
+ * }, function(err) {
+ *   console.log(key.path); // ['Company', 'donutshack']
+ *   console.log(key.namespace); // undefined
+ * });
+ *
+ * //-
+ * // Save a single entity with a provided namespace. Namespaces allow for
+ * // multitenancy. To read more about this, see
+ * // [the Datastore docs on key concepts](https://goo.gl/M1LUAu).
+ * //
+ * // Here we are providing a key with namespace.
+ * //-
+ * var key = dataset.key({
+ *   namespace: 'my-namespace',
+ *   path: ['Company', 'donutshack']
+ * });
+ *
+ * dataset.save({
+ *   key: key,
+ *   data: {
+ *     name: 'DonutShack',
+ *     rating: 8
+ *   }
+ * }, function(err) {
+ *   console.log(key.path); // ['Company', 'donutshack']
+ *   console.log(key.namespace); // 'my-namespace'
+ * });
+ *
+ * //-
+ * // Save different types of data, including ints, doubles, dates, booleans,
+ * // blobs, and lists.
+ * //
+ * // Notice that we are providing an incomplete key. After saving, the original
+ * // Key object used to save will be updated to contain the path with its
+ * // generated ID.
+ * //-
+ * var key = dataset.key('Company');
+ *
+ * dataset.save({
+ *   key: key,
+ *   data: {
+ *     name: 'DonutShack', // strings
+ *     rating: datastore.int(8), // ints
+ *     worth: datastore.double(123456.78), // doubles
+ *     numDonutsServed: 45, // detect number type (int or double)
+ *     founded: new Date('Tue May 12 2015 15:30:00 GMT-0400 (EDT)'), // dates
+ *     isStartup: true, // booleans
+ *     donutEmoji: new Buffer('\uD83C\uDF69'), // buffers
+ *     keywords: ['donut', 'coffee', 'yum'] // lists of objects
+ *   }
  * }, function(err) {});
  *
  * //-