examples in each file now tested in own sandbox

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:

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
@@ -190,6 +197,7 @@ 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) {

lib/datastore/dataset.js

@@ -78,6 +78,7 @@ var SCOPES = [
  *
  * @example
  * var datastore = gcloud.datastore;
+ *
  * var dataset = datastore.dataset({
  *   projectId: 'my-project',
  *   keyFilename: '/path/to/keyfile.json'

lib/datastore/query.js

@@ -44,6 +44,8 @@ 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.
  * var query = dataset.createQuery('Lion');

lib/datastore/request.js

@@ -64,6 +64,15 @@ var MODE_TRANSACTIONAL = 'TRANSACTIONAL';
  *
  * Creates requests to the Dataset endpoint. Designed to be inherited by
  * datastore.Dataset and datastore.Transaction objects.
+ *
+ * @example
+ * // 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.
@@ -90,10 +99,10 @@ function DatastoreRequest() {}
  *
  * // Get a single entity.
  * var key = dataset.key(['Company', 123]);
- * dataset.get(key, function(err, entity, apiResponse) {});
+ * transaction.get(key, function(err, entity, apiResponse) {});
  *
  * // Get multiple entities at once.
- * dataset.get([
+ * transaction.get([
  *   dataset.key(['Company', 123]),
  *   dataset.key(['Product', 'Computer'])
  * ], function(err, entities, apiResponse) {});
@@ -415,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) {});
@@ -460,21 +474,26 @@ DatastoreRequest.prototype.delete = function(keys, callback) {
  *     stream instance is returned.
  *
  * @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 query = dataset.createQuery('Lion');
  *
  * // Retrieve 5 companies.
- * dataset.runQuery(query, function(err, entities, endCursor, apiResponse) {
+ * transaction.runQuery(query, function(err, entities, endCursor, apiResponse) {
  *   // Use `endCursor` as the starting cursor for your next query.
  *   var nextQuery = query.start(endCursor);
  *   var callback = function(err, entities, endCursor, apiResponse) {};
- *   dataset.runQuery(nextQuery, callback);
+ *   transaction.runQuery(nextQuery, 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.
  * //-
- * dataset.runQuery(query)
+ * transaction.runQuery(query)
  *   .on('data', function (entity) {});
  */
 DatastoreRequest.prototype.runQuery = function(q, callback) {
@@ -556,15 +575,15 @@ DatastoreRequest.prototype.runQuery = function(q, callback) {
  *
  * @example
  * //-
- * // Where you see `dataset`, assume this is the context that's relevant to
+ * // 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) {});
+ * transaction.allocateIds(incompleteKey, 100, function(err, keys) {});
  *
  * // You may prefer to create IDs from a non-default namespace by providing an
  * // incomplete key with a namespace. Similar to the previous example, the call
@@ -575,7 +594,7 @@ DatastoreRequest.prototype.runQuery = function(q, callback) {
  *   path: ['Company']
  * });
  * var callback = function(err, keys, apiResponse) {};
- * dataset.allocateIds(incompleteKey, 100, callback);
+ * transaction.allocateIds(incompleteKey, 100, callback);
  */
 DatastoreRequest.prototype.allocateIds = function(incompleteKey, n, callback) {
   if (entity.isKeyComplete(incompleteKey)) {
@@ -635,6 +654,8 @@ DatastoreRequest.prototype.upsert = function(entities, callback) {
  *     delete: [] // datastore key objects.
  *   }
  * };
+ *
+ * var dataset = gcloud.datastore.dataset();
  * var callback = function(err, result, apiResponse) {};
  * var Transaction = require('gcloud/lib/datastore/transaction');
  * var transaction = new Transaction(dataset, 'my-project-id');

lib/datastore/transaction.js

@@ -47,6 +47,7 @@ var extend = require('extend');
  * // 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.
@@ -263,13 +264,13 @@ Transaction.prototype.commit_ = function(callback) {
  *
  * @example
  * // Delete a single entity.
- * transaction.delete(dataset.key(['Company', 123]), function(err) {});
+ * transaction.delete(dataset.key(['Company', 123]));
  *
  * // Delete multiple entities at once.
  * transaction.delete([
  *   dataset.key(['Company', 123]),
  *   dataset.key(['Product', 'Computer'])
- * ], function(err) {});
+ * ]);
  */
 Transaction.prototype.delete = function(entities) {
   var that = this;

lib/pubsub/subscription.js

@@ -62,6 +62,8 @@ var util = require('../common/util.js');
  * @constructor
  *
  * @example
+ * var pubsub = gcloud.pubsub();
+ *
  * //-
  * // From {@linkcode module:pubsub#getSubscriptions}:
  * //-

lib/pubsub/topic.js

@@ -47,6 +47,8 @@ var Subscription = require('./subscription.js');
  * @alias module:pubsub/topic
  *
  * @example
+ * var pubsub = gcloud.pubsub();
+ *
  * // From pubsub.topic:
  * var topic = pubsub.topic('my-existing-topic');
  *

lib/storage/acl.js

@@ -99,6 +99,8 @@ function Acl(options) {
  * @return {object}
  *
  * @example
+ * var storage = gcloud.storage();
+ *
  * //-
  * // Add a user as an owner of a file.
  * //-

lib/storage/bucket.js

@@ -126,6 +126,7 @@ function Bucket(storage, name) {
    * //-
    * // Make a bucket's contents publicly readable.
    * //-
+   * var myBucket = storage.bucket('my-bucket');
    * myBucket.acl.add({
    *   scope: 'allUsers',
    *   role: storage.acl.READER_ROLE
@@ -218,12 +219,14 @@ function Bucket(storage, name) {
  * @param {function=} callback - The callback function.
  *
  * @example
- * var logs2013 = bucket.file('2013-logs.txt');
- * var logs2014 = bucket.file('2014-logs.txt');
+ * var logBucket = storage.bucket('log-bucket');
  *
- * var allLogs = bucket.file('all-logs.txt');
+ * var logs2013 = logBucket.file('2013-logs.txt');
+ * var logs2014 = logBucket.file('2014-logs.txt');
  *
- * bucket.combine([
+ * var allLogs = logBucket.file('all-logs.txt');
+ *
+ * logBucket.combine([
  *   logs2013,
  *   logs2014
  * ], allLogs, function(err, newFile, apiResponse) {
@@ -303,6 +306,7 @@ Bucket.prototype.combine = function(sources, destination, callback) {
  * @param {function=} callback - The callback function.
  *
  * @example
+ * var bucket = storage.bucket('delete-me');
  * bucket.delete(function(err, apiResponse) {});
  */
 Bucket.prototype.delete = function(callback) {

lib/storage/file.js

@@ -107,6 +107,8 @@ function File(bucket, name, options) {
    * //-
    * // Make a file publicly readable.
    * //-
+   * var storage = gcloud.storage();
+   * var myFile = storage.bucket('my-bucket').file('my-file');
    * myFile.acl.add({
    *   scope: 'allUsers',
    *   role: storage.acl.READER_ROLE
@@ -367,6 +369,7 @@ File.prototype.move = function(destination, callback) {
  * // backup of your remote data.
  * //-
  * var fs = require('fs');
+ * var myBucket = storage.bucket('my-bucket');
  * var image = myBucket.file('image.png');
  *
  * image.createReadStream()

scripts/build.sh

@@ -17,7 +17,7 @@
 set -ev
 
 npm run lint
-npm run docs
+# generates docs and runs tests
 npm run test
 
 # if merging to master and not a pull request, execute system tests, create coverage report and update docs
@@ -26,8 +26,7 @@ if [ "${TRAVIS_BRANCH}" == "master" ] && [ "${TRAVIS_PULL_REQUEST}" == "false" ]
   # create new coverage report (executes system tests)
   npm run coveralls
 
-  # generate new set of json files in docs/json/master
-  npm run docs
+  # add new docs to the gh-pages branch
   git submodule add -b gh-pages https://${GH_OAUTH_TOKEN}@github.com/${GH_OWNER}/${GH_PROJECT_NAME} ghpages
   # copy all the docs file that might have changed, excluding versions.txt (to avoid overriding it)
   cd docs

test/common/docs.js

@@ -25,16 +25,7 @@ var glob = require('glob');
 var mitm = require('mitm');
 var fs = require('fs');
 
-var sandbox = {
-  gcloud: gcloud,
-  require: require,
-  process: process,
-  Buffer: Buffer,
-  Date: Date,
-  Array: Array
-};
-
-function runCodeInSandbox(code) {
+function runCodeInSandbox(code, sandbox) {
   vm.createContext(sandbox);
   try {
     vm.runInNewContext(code, sandbox, {
@@ -54,7 +45,7 @@ describe('documentation', function() {
   before(function(done) {
     // Turn off the network so that API calls aren't actually made.
     MITM = mitm();
-    glob('docs/json/**/*.json', {}, function(err, files) {
+    glob('docs/json/master/**/*.json', function(err, files) {
       assert.ifError(err);
       FILES = files;
       done();
@@ -67,36 +58,43 @@ describe('documentation', function() {
   });
 
   it('should run docs examples without errors', function() {
-    for (var f in FILES) {
+    FILES.forEach(function(filename) {
       var fileDocBlocks = [];
-      var fileContents = fs.readFileSync(FILES[f], {
+      var fileContents = fs.readFileSync(filename, {
         encoding: 'utf8'
       });
 
       try {
         fileDocBlocks = JSON.parse(fileContents);
       } catch(e) {
-        throw new Error('Failed to parse one of the doc files (' + e.message +
-            ')\n\nFilename: ' + FILES[f] + '\n\nFile contents: \'' +
-            fileContents + '\'');
+        throw new Error([
+          'Failed to parse one of the doc files (' + e.message + ')',
+          'Filename: ' + filename,
+          'File contents: "' + fileContents + '"'
+        ].join('\n'));
       }
 
-      for (var i in fileDocBlocks) {
-        var tags = fileDocBlocks[i].tags;
-        for (var j in tags) {
-          var tag = tags[j];
+      var sandbox = {
+        gcloud: gcloud,
+        require: require,
+        process: process,
+        Buffer: Buffer,
+        Date: Date,
+        Array: Array
+      };
 
-          // Only blocks under @example are tested.
+      fileDocBlocks.forEach(function(block) {
+        block.tags.forEach(function(tag) {
           if (tag.type === 'example') {
             // Replace all references to require('gcloud') with a relative
             // version so that the code can be passed into the VM directly.
             var code = tag.string
-                .replace('require(\'gcloud\')', 'require(\'..\/..\/\')')
-                .replace('require(\'gcloud', 'require(\'..\/..');
-            assert.doesNotThrow(runCodeInSandbox.bind(null, code));
+                .replace(/require\(\'gcloud\'\)/g, 'require(\'..\/..\/\')')
+                .replace(/require\(\'gcloud/g, 'require(\'..\/..');
+            assert.doesNotThrow(runCodeInSandbox.bind(null, code, sandbox));
           }
-        }
-      }
-    }
+        });
+      });
+    });
   });
 });