Merge pull request #627 from ryanseys/verify-docs

Verify @example docs on npm test

lib/bigquery/dataset.js

@@ -73,6 +73,8 @@ function Dataset(bigQuery, id) {
  *   schema: 'UNITID,INSTNM,ADDR,CITY,STABBR,ZIP,FIPS,OBEREG,CHFNM,...'
  * };
  *
+ * var bigquery = gcloud.bigquery();
+ * var dataset = bigquery.dataset();
  * dataset.createTable(tableConfig, function(err, table, apiResponse) {});
  */
 Dataset.prototype.createTable = function(options, callback) {

lib/bigquery/index.js

@@ -77,7 +77,7 @@ var SCOPES = ['https://www.googleapis.com/auth/bigquery'];
  *   projectId: 'my-project'
  * });
  *
- * var bigquery = myProject.bigquery();
+ * var bigquery = gcloud.bigquery();
  *
  * //-
  * // In the following examples from this page and the other modules (Dataset,

lib/bigquery/job.js

@@ -29,7 +29,12 @@ var util = require('../common/util');
 /*! Developer Documentation
  *
  * @param {module:bigquery} bigQuery - BigQuery instance.
- * @param {string} id - The ID of the table.
+ * @param {string} id - The ID of the job.
+ *
+ * @example
+ * var bigquery = gcloud.bigquery();
+ * var Job = require('gcloud/lib/bigquery/job');
+ * var job = new Job(bigquery, 'job-id');
  */
 /**
  * Job objects are returned from various places in the BigQuery API:
@@ -62,6 +67,7 @@ function Job(bigQuery, id) {
  * @param {function} callback - The callback function.
  *
  * @example
+ * var job = bigquery.job('id');
  * job.getMetadata(function(err, metadata, apiResponse) {});
  */
 Job.prototype.getMetadata = function(callback) {
@@ -117,12 +123,13 @@ Job.prototype.getMetadata = function(callback) {
  * // Consume the results from the query as a readable stream.
  * //-
  * var through2 = require('through2');
+ * var fs = require('fs');
  *
  * job.getQueryResults(options)
  *   .pipe(through2.obj(function (row, enc, next) {
  *     this.push(JSON.stringify(row) + '\n');
  *   }))
- *   .pipe(fs.createWriteStream('./backup.json'));
+ *   .pipe(fs.createWriteStream('./test/testdata/testfile.json'));
  */
 Job.prototype.getQueryResults = function(options, callback) {
   if (util.is(options, 'function')) {

lib/bigquery/table.js

@@ -44,6 +44,13 @@ var util = require('../common/util');
  *
  * @param {module:bigquery/dataset} dataset - Dataset instance.
  * @param {string} id - The ID of the table.
+ *
+ * @example
+ * var bigquery = gcloud.bigquery();
+ * var Dataset = require('gcloud/lib/bigquery/dataset');
+ * var dataset = new Dataset(bigquery, 'dataset-id');
+ * var Table = require('gcloud/lib/bigquery/table');
+ * var table = new Table(dataset, 'table-id');
  */
 /**
  * Table objects are returned by methods such as
@@ -52,6 +59,9 @@ var util = require('../common/util');
  *
  * @alias module:bigquery/table
  * @constructor
+ *
+ * @example
+ * var table = dataset.table('my-table');
  */
 function Table(dataset, id) {
   this.bigQuery = dataset.bigQuery;
@@ -124,7 +134,8 @@ Table.mergeSchemaWithRows_ = function(schema, rows) {
  * @throws {Error} If a destination other than a Table object is provided.
  *
  * @example
- * table.copy(dataset.table('my-table'), function(err, job, apiResponse) {});
+ * var yourTable = dataset.table('your-table');
+ * table.copy(yourTable, function(err, job, apiResponse) {});
  *
  * //-
  * // See the [`configuration.copy`](http://goo.gl/dKWIyS) object for all
@@ -135,7 +146,7 @@ Table.mergeSchemaWithRows_ = function(schema, rows) {
  *   writeDisposition: 'WRITE_TRUNCATE'
  * };
  *
- * table.copy(options, metadata, function(err, job, apiResponse) {});
+ * table.copy(yourTable, metadata, function(err, job, apiResponse) {});
  */
 Table.prototype.copy = function(destination, metadata, callback) {
   var that = this;
@@ -186,12 +197,13 @@ Table.prototype.copy = function(destination, metadata, callback) {
  *
  * @example
  * var through2 = require('through2');
+ * var fs = require('fs');
  *
  * table.createReadStream()
  *   .pipe(through2.obj(function(row, enc, next) {
  *     this.push(JSON.stringify(row) + '\n');
  *   }))
- *   .pipe(fs.createWriteStream('./institutions.json'));
+ *   .pipe(fs.createWriteStream('./test/testdata/testfile.json'));
  */
 Table.prototype.createReadStream = function() {
   var that = this;
@@ -261,7 +273,7 @@ Table.prototype.createReadStream = function() {
  * //-
  * var fs = require('fs');
  *
- * fs.createReadStream('./institutions.json')
+ * fs.createReadStream('./test/testdata/testfile.json')
  *   .pipe(table.createWriteStream('json'))
  *   .on('complete', function(job) {});
  */
@@ -357,6 +369,7 @@ Table.prototype.delete = function(callback) {
  * @throws {Error} If destination format isn't recongized.
  *
  * @example
+ * var storage = gcloud.storage();
  * var exportedFile = storage.bucket('institutions').file('2014.csv');
  *
  * //-
@@ -499,7 +512,7 @@ Table.prototype.getMetadata = function(callback) {
  *   if (nextQuery) {
  *     table.getRows(nextQuery, function(err, rows, nextQuery, apiResponse) {});
  *   }
- * });`
+ * });
  */
 Table.prototype.getRows = function(options, callback) {
   var that = this;
@@ -585,7 +598,7 @@ Table.prototype.getRows = function(options, callback) {
  * //-
  * var metadata = {
  *   encoding: 'ISO-8859-1',
- *   sourceFormat: 'JSON'
+ *   sourceFormat: 'NEWLINE_DELIMITED_JSON'
  * };
  *
  * table.import('./my-data.csv', metadata, function(err, job, apiResponse) {});

lib/datastore/dataset.js

@@ -77,6 +77,8 @@ var SCOPES = [
  * @param {string} options.namespace - Namespace to isolate transactions to.
  *
  * @example
+ * var datastore = gcloud.datastore;
+ *
  * var dataset = datastore.dataset({
  *   projectId: 'my-project',
  *   keyFilename: '/path/to/keyfile.json'
@@ -208,7 +210,10 @@ Dataset.prototype.createQuery = function(namespace, kind) {
 
 /**
  * Run a function in the context of a new transaction. Transactions allow you to
- * perform multiple operations, committing your changes atomically.
+ * perform multiple operations, committing your changes atomically. When you are
+ * finished making your changes within the transaction, run the done() function
+ * provided in the callback function to commit your changes. See an example
+ * below for more information.
  *
  * @borrows {module:datastore/transaction#begin} as runInTransaction
  *
@@ -232,13 +237,13 @@ Dataset.prototype.createQuery = function(namespace, kind) {
 Dataset.prototype.runInTransaction = function(fn, callback) {
   var newTransaction = this.createTransaction_();
 
-  newTransaction.begin(function(err) {
+  newTransaction.begin_(function(err) {
     if (err) {
       callback(err);
       return;
     }
 
-    fn(newTransaction, newTransaction.commit.bind(newTransaction, callback));
+    fn(newTransaction, newTransaction.commit_.bind(newTransaction, callback));
   });
 };
 

lib/datastore/entity.js

@@ -411,7 +411,7 @@ function valueToProperty(v) {
     p.blob_value = v;
     return p;
   }
-  if (v instanceof Array) {
+  if (Array.isArray(v)) {
     p.list_value = v.map(function(item) {
       return valueToProperty(item);
     });

lib/datastore/index.js

@@ -41,13 +41,11 @@ var Dataset = require('./dataset');
 /*! Developer Documentation
  *
  * Invoking the Datastore class allows you to provide configuration up-front.
- * This configuration will be used for future invokations of the returned
+ * This configuration will be used for future invocations of the returned
  * `dataset` method.
  *
  * @example
- * var datastore = require('gcloud/lib/datastore')({
- *   keyFilename: '/path/to/keyfile.json'
- * });
+ * var datastore = gcloud.datastore;
  *
  * var dataset = datastore.dataset();
  * // equal to:
@@ -82,7 +80,7 @@ function Datastore(options) {
  * options.
  *
  * @example
- * var datastore = require('gcloud/lib/datastore');
+ * var datastore = gcloud.datastore;
  *
  * // Create a Dataset object.
  * var dataset = datastore.dataset({

lib/datastore/query.js

@@ -44,15 +44,17 @@ var util = require('../common/util.js');
  * @param {string} kind - Kind to query.
  *
  * @example
+ * var dataset = gcloud.datastore.dataset();
+ *
  * // If your dataset was scoped to a namespace at initialization, your query
  * // will likewise be scoped to that namespace.
- * dataset.createQuery('Lion');
+ * var query = dataset.createQuery('Lion');
  *
  * // However, you may override the namespace per query.
- * dataset.createQuery('AnimalNamespace', 'Lion');
+ * var query = dataset.createQuery('AnimalNamespace', 'Lion');
  *
  * // You may also remove the namespace altogether.
- * dataset.createQuery(null, 'Lion');
+ * var query = dataset.createQuery(null, 'Lion');
  */
 function Query(namespace, kinds) {
   if (!kinds) {
@@ -91,7 +93,7 @@ function Query(namespace, kinds) {
  * @example
  * // List all companies named Google that have less than 400 employees.
  * var companyQuery = query
- *   .filter('name =', 'Google');
+ *   .filter('name =', 'Google')
  *   .filter('size <', 400);
  *
  * // To filter by key, use `__key__` for the property name. Filter on keys

lib/datastore/request.js

@@ -66,9 +66,13 @@ var MODE_TRANSACTIONAL = 'TRANSACTIONAL';
  * datastore.Dataset and datastore.Transaction objects.
  *
  * @example
- * // Inherit in Dataset and Transaction
- * require('util').inherits(Dataset, DatastoreRequest);
- * require('util').inherits(Transaction, DatastoreRequest);
+ * // This is how to create a transaction object directly using this Transaction
+ * // class. The following transaction object is created for use in the examples
+ * // in this file below.
+ * var dataset = gcloud.datastore.dataset();
+ * var Transaction = require('gcloud/lib/datastore/transaction');
+ * var transaction = new Transaction(dataset, 'my-project-id');
+ * transaction.id = '1234'; // Give the transaction an ID.
  */
 /*
  * Handle logic for Datastore API operations.
@@ -258,13 +262,13 @@ DatastoreRequest.prototype.insert = function(entities, callback) {
  *   key: key,
  *   data: {
  *     name: 'DonutShack', // strings
- *     rating: datastore.int(8), // ints
- *     worth: datastore.double(123456.78), // doubles
+ *     rating: gcloud.datastore.int(8), // ints
+ *     worth: gcloud.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
+ *     keywords: [ 'donut', 'coffee', 'yum' ] // lists of objects
  *   }
  * }, function(err) {});
  *
@@ -420,11 +424,16 @@ DatastoreRequest.prototype.save = function(entities, callback) {
  * @param {function} callback - The callback function.
  *
  * @example
+ * //-
+ * // 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.
+ * //-
+ *
  * // Delete a single entity.
- * dataset.delete(dataset.key(['Company', 123]), function(err) {});
+ * transaction.delete(dataset.key(['Company', 123]), function(err, apiResp) {});
  *
  * // Delete multiple entities at once.
- * dataset.delete([
+ * transaction.delete([
  *   dataset.key(['Company', 123]),
  *   dataset.key(['Product', 'Computer'])
  * ], function(err, apiResponse) {});
@@ -469,6 +478,7 @@ DatastoreRequest.prototype.delete = function(keys, callback) {
  * // 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 query = dataset.createQuery('Lion');
  *
  * // Retrieve 5 companies.
  * transaction.runQuery(query, function(err, entities, endCursor, apiResponse) {
@@ -483,7 +493,7 @@ DatastoreRequest.prototype.delete = function(keys, callback) {
  * // queries until no results remain. Entity objects will be pushed as they are
  * // found.
  * //-
- * transaction.runQuery(queryObject)
+ * transaction.runQuery(query)
  *   .on('data', function (entity) {});
  */
 DatastoreRequest.prototype.runQuery = function(q, callback) {
@@ -569,6 +579,8 @@ DatastoreRequest.prototype.runQuery = function(q, callback) {
  * // 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.
  * transaction.allocateIds(incompleteKey, 100, function(err, keys) {});
@@ -642,8 +654,12 @@ DatastoreRequest.prototype.upsert = function(entities, callback) {
  *     delete: [] // datastore key objects.
  *   }
  * };
+ *
+ * var dataset = gcloud.datastore.dataset();
  * var callback = function(err, result, apiResponse) {};
- * transaction.makeReq('commit', deleteRequest, callback);
+ * var Transaction = require('gcloud/lib/datastore/transaction');
+ * var transaction = new Transaction(dataset, 'my-project-id');
+ * transaction.makeReq_('commit', deleteRequest, callback);
  */
 DatastoreRequest.prototype.makeReq_ = function(method, body, callback) {
   // TODO: Handle non-HTTP 200 cases.
@@ -664,6 +680,10 @@ DatastoreRequest.prototype.makeReq_ = function(method, body, callback) {
     }
   }
 
+  if (method === 'rollback') {
+    body.transaction = this.id;
+  }
+
   if (method === 'lookup' && this.id) {
     body.read_options = body.read_options || {};
     body.read_options.transaction = this.id;