spanner: transaction docs (googleapis#2009)

packages/spanner/src/database.js

@@ -571,7 +571,7 @@ Database.prototype.run = function(query, options, callback) {
  * database.runStream(query)
  *   .on('error', function(err) {})
  *   .on('data', function(row) {})
- *   .on('end', function() {})
+ *   .on('end', function() {});
  *
  * //-
  * // If you anticipate many results, you can end a stream early to prevent
@@ -804,7 +804,7 @@ Database.prototype.table = function(name) {
  *   ') PRIMARY KEY(SingerId)'
  * ];
  *
- * database.setSchema(statements, function(err, operation, apiResponse) {
+ * database.updateSchema(statements, function(err, operation, apiResponse) {
  *   if (err) {
  *     // Error handling omitted.
  *   }
@@ -819,7 +819,7 @@ Database.prototype.table = function(name) {
  * //-
  * // If the callback is omitted, we'll return a Promise.
  * //-
- * database.setSchema(statements)
+ * database.updateSchema(statements)
  *   .then(function(data) {
  *     var operation = data[0];
  *     return operation.promise();

packages/spanner/src/table.js

@@ -97,7 +97,6 @@ util.inherits(Table, TransactionRequest);
  *   .then(function() {
  *     // Table created successfully.
  *   });
- * });
  */
 Table.prototype.create = function(schema, callback) {
   this.database.createTable(schema, callback);
@@ -154,7 +153,10 @@ Table.prototype.create = function(schema, callback) {
  * // If you anticipate many results, you can end a stream early to prevent
  * // unnecessary processing and API requests.
  * //-
- * table.createReadStream()
+ * table.createReadStream({
+ *     keys: ['1'],
+ *     columns: ['SingerId', 'name']
+ *   })
  *   .on('data', function(row) {
  *     this.end();
  *   });

packages/spanner/src/transaction-request.js

@@ -119,7 +119,7 @@ TransactionRequest.formatTimestampOptions_ = function(options) {
  * @return {Stream}
  *
  * @example
- * database.runTransaction(function(err) {
+ * database.runTransaction(function(err, transaction) {
  *   if (err) {
  *     // Error handling omitted.
  *   }
@@ -150,7 +150,7 @@ TransactionRequest.formatTimestampOptions_ = function(options) {
  * // Rows are returned as an array of object arrays. Each object has a `name`
  * // and `value` property. To get a serialized object, call `toJSON()`.
  * //-
- * database.runTransaction(function(err) {
+ * database.runTransaction(function(err, transaction) {
  *   if (err) {
  *     // Error handling omitted.
  *   }
@@ -236,25 +236,41 @@ TransactionRequest.prototype.createReadStream = function(table, query) {
  * @example
  * var keys = ['Id1', 'Id2', 'Id3'];
  *
- * database.runTransaction(function(err) {
+ * database.runTransaction(function(err, transaction) {
  *   if (err) {
  *     // Error handling omitted.
  *   }
  *
- *   transaction.deleteRows('Singers', keys, function(err, apiResponse) {});
+ *   // Queue this mutation until later calling `commit`.
+ *   // Note that a callback is not passed to `deleteRows`.
+ *   transaction.deleteRows('Singers', keys);
+ *
+ *   // Commit the transaction.
+ *   transaction.commit(function(err) {
+ *     if (!err) {
+ *       // The rows were deleted successfully.
+ *     }
+ *   });
  * });
  *
  * //-
- * // If the callback is omitted, we'll return a Promise.
+ * // If you are using a Promise to retrieve the transaction.
  * //-
  * database.runTransaction()
  *   .then(function(data) {
  *     var transaction = data[0];
  *
- *     transaction.deleteRows('Singers', keys)
- *       .then(function(data) {
- *         var apiResponse = data[0];
- *       });
+ *     // Queue this mutation until later calling `commit`.
+ *     // Note that a callback is not passed to `deleteRows`.
+ *     transaction.deleteRows('Singers', keys);
+ *
+ *     // Commit the transaction.
+ *     return transaction.commit();
+ *   })
+ *   .then(function(data) {
+ *     var apiResponse = data[0];
+ *
+ *     // The rows were deleted successfully.
  *   });
  */
 TransactionRequest.prototype.deleteRows = function(table, keys, callback) {
@@ -312,6 +328,13 @@ TransactionRequest.prototype.deleteRows = function(table, keys, callback) {
  *   // Queue this mutation until later calling `commit`.
  *   // Note that a callback is not passed to `insert`.
  *   transaction.insert(row);
+ *
+ *   // Commit the transaction.
+ *   transaction.commit(function(err) {
+ *     if (!err) {
+ *       // The row was inserted successfully.
+ *     }
+ *   });
  * });
  *
  * //-
@@ -333,7 +356,34 @@ TransactionRequest.prototype.deleteRows = function(table, keys, callback) {
  *     row,
  *     row2
  *   ]);
+ *
+ *   // Commit the transaction.
+ *   transaction.commit(function(err) {
+ *     if (!err) {
+ *       // The rows were inserted successfully.
+ *     }
+ *   });
  * });
+ *
+ * //-
+ * // If you are using a Promise to retrieve the transaction.
+ * //-
+ * database.runTransaction()
+ *   .then(function(data) {
+ *     var transaction = data[0];
+ *
+ *     // Queue this mutation until later calling `commit`.
+ *     // Note that a callback is not passed to `insert`.
+ *     transaction.insert(row);
+ *
+ *     // Commit the transaction.
+ *     return transaction.commit();
+ *   })
+ *   .then(function(data) {
+ *     var apiResponse = data[0];
+ *
+ *     // The row was inserted successfully.
+ *   });
  */
 TransactionRequest.prototype.insert = function(table, keyVals, callback) {
   return this.mutate_('insert', table, keyVals, callback);
@@ -473,8 +523,14 @@ TransactionRequest.prototype.read = function(table, keyVals, callback) {
  *   // Queue this mutation until later calling `commit`.
  *   // Note that a callback is not passed to `replace`.
  *   transaction.replace('Singers', row);
- * });
  *
+ *   // Commit the transaction.
+ *   transaction.commit(function(err) {
+ *     if (!err) {
+ *       // The row was replaced successfully.
+ *     }
+ *   });
+ * });
  *
  * //-
  * // If you are using a Promise to retrieve the transaction.
@@ -486,6 +542,14 @@ TransactionRequest.prototype.read = function(table, keyVals, callback) {
  *     // Queue this mutation until later calling `commit`.
  *     // Note that a callback is not passed to `replace`.
  *     transaction.replace('Singers', row);
+ *
+ *     // Commit the transaction.
+ *     return transaction.commit();
+ *   })
+ *   .then(function(data) {
+ *     var apiResponse = data[0];
+ *
+ *     // The row was replaced successfully.
  *   });
  */
 TransactionRequest.prototype.replace = function(table, keyVals, callback) {
@@ -537,8 +601,14 @@ TransactionRequest.prototype.requestStream = function() {};
  *   // Queue this mutation until later calling `commit`.
  *   // Note that a callback is not passed to `update`.
  *   transaction.update('Singers', row);
- * });
  *
+ *   // Commit the transaction.
+ *   transaction.commit(function(err) {
+ *     if (!err) {
+ *       // The row was updated successfully.
+ *     }
+ *   });
+ * });
  *
  * //-
  * // If you are using a Promise to retrieve the transaction.
@@ -550,6 +620,14 @@ TransactionRequest.prototype.requestStream = function() {};
  *     // Queue this mutation until later calling `commit`.
  *     // Note that a callback is not passed to `update`.
  *     transaction.update('Singers', row);
+ *
+ *     // Commit the transaction.
+ *     return transaction.commit();
+ *   })
+ *   .then(function(data) {
+ *     var apiResponse = data[0];
+ *
+ *     // The row was updated successfully.
  *   });
  */
 TransactionRequest.prototype.update = function(table, keyVals, callback) {
@@ -583,8 +661,14 @@ TransactionRequest.prototype.update = function(table, keyVals, callback) {
  *   // Queue this mutation until later calling `commit`.
  *   // Note that a callback is not passed to `upsert`.
  *   transaction.upsert('Singers', row);
- * });
  *
+ *   // Commit the transaction.
+ *   transaction.commit(function(err) {
+ *     if (!err) {
+ *       // The row was updated or inserted successfully.
+ *     }
+ *   });
+ * });
  *
  * //-
  * // If you are using a Promise to retrieve the transaction.
@@ -596,6 +680,14 @@ TransactionRequest.prototype.update = function(table, keyVals, callback) {
  *     // Queue this mutation until later calling `commit`.
  *     // Note that a callback is not passed to `upsert`.
  *     transaction.upsert('Singers', row);
+ *
+ *     // Commit the transaction.
+ *     return transaction.commit();
+ *   })
+ *   .then(function(data) {
+ *     var apiResponse = data[0];
+ *
+ *     // The row was updated or inserted successfully.
  *   });
  */
 TransactionRequest.prototype.upsert = function(table, keyVals, callback) {

packages/spanner/src/transaction.js

@@ -519,7 +519,7 @@ Transaction.prototype.run = function(query, callback) {
  *   transaction.runStream(query)
  *     .on('error', function(err) {})
  *     .on('data', function(row) {})
- *     .on('end', function() {})
+ *     .on('end', function() {});
  * });
  *
  * //-

test/docs.js

@@ -50,7 +50,7 @@ var DocsError = createErrorClass('DocsError', function(err, code) {
 
 var JSHintError = createErrorClass('JSHintError', function(err) {
   this.message = format('"{evidence}" - {reason}', {
-    evidence: err.evidence.trim(),
+    evidence: err.evidence && err.evidence.trim(),
     reason: err.reason
   });
 
@@ -218,7 +218,9 @@ function createInstantiationCode(mod) {
     if (api) {
       Object.keys(api).forEach(function(apiName) {
         Object.keys(api[apiName]).forEach(function(method) {
-          api[apiName][method] = function() {};
+          api[apiName][method] = function() {
+            return Promise.resolve();
+          };
         });
       });
     }