update tests + docs

Author: stephenplusplus

lib/storage/bucket.js

@@ -411,11 +411,11 @@ Bucket.prototype.getMetadata = function(callback) {
 };
 
 /**
- * Make the bucket publicly readable.
+ * Make the bucket listing private.
  *
- * You may also choose to make the contents of the bucket publicly readable by
- * specifying `includeFiles: true`. This will automatically run
- * {module:storage/file#makePublic} for every file in the bucket.
+ * You may also choose to make the contents of the bucket private by specifying
+ * `includeFiles: true`. This will automatically run
+ * {module:storage/file#makePrivate} for every file in the bucket.
  *
  * When specifying `includeFiles: true`, use `force: true` to delay execution of
  * your callback until all files have been processed. By default, the callback
@@ -427,51 +427,51 @@ Bucket.prototype.getMetadata = function(callback) {
  * requests. Use with caution.
  *
  * @param {object=} options - The configuration object.
- * @param {boolean} options.includeFiles - Make each file in the bucket publicly
- *     readable. Default: `false`.
+ * @param {boolean} options.includeFiles - Make each file in the bucket private.
+ *     Default: `false`.
  * @param {boolean} options.force - Queue errors occurred while making files
- *     public until all files have been processed.
+ *     private until all files have been processed.
  * @param {function} callback - The callback function.
  *
  * @example
  * //-
- * // Make the bucket publicly readable.
+ * // Make the bucket private.
  * //-
- * bucket.makePublic(function(err) {});
+ * bucket.makePrivate(function(err) {});
  *
  * //-
- * // Make the bucket and its contents publicly readable.
+ * // Make the bucket and its contents private.
  * //-
  * var opts = {
  *   includeFiles: true
  * };
  *
- * bucket.makePublic(opts, function(err, files) {
+ * bucket.makePrivate(opts, function(err, files) {
  *   // `err`:
  *   //    The first error to occur, otherwise null.
  *   //
  *   // `files`:
- *   //    Array of files successfully made public in the bucket.
+ *   //    Array of files successfully made private in the bucket.
  * });
  *
  * //-
- * // Make the bucket and its contents publicly readable, using force to
- * // suppress errors until all files have been processed.
+ * // Make the bucket and its contents private, using force to suppress errors
+ * // until all files have been processed.
  * //-
  * var opts = {
  *   includeFiles: true,
  *   force: true
  * };
  *
- * bucket.makePublic(opts, function(errors, files) {
+ * bucket.makePrivate(opts, function(errors, files) {
  *   // `errors`:
  *   //    Array of errors if any occurred, otherwise null.
  *   //
  *   // `files`:
- *   //    Array of files successfully made public in the bucket.
+ *   //    Array of files successfully made private in the bucket.
  * });
  */
-Bucket.prototype.makePublic = function(options, callback) {
+Bucket.prototype.makePrivate = function(options, callback) {
   var self = this;
 
   if (util.is(options, 'function')) {
@@ -480,27 +480,15 @@ Bucket.prototype.makePublic = function(options, callback) {
   }
 
   options = options || {};
-  options.public = true;
+  options.private = true;
 
-  async.parallel([
-    setPredefinedAcl,
-    addAclPermissions,
-    makeFilesPublic
-  ], callback);
+  async.parallel([setPredefinedAcl, makeFilesPrivate], callback);
 
   function setPredefinedAcl(done) {
     self.setPredefinedAcl_(options, done);
   }
 
-  function addAclPermissions(done) {
-    // Allow reading bucket contents while preserving original permissions.
-    self.acl.default.add({
-      entity: 'allUsers',
-      role: 'READER'
-    }, done);
-  }
-
-  function makeFilesPublic(done) {
+  function makeFilesPrivate(done) {
     if (!options.includeFiles) {
       done();
       return;
@@ -511,11 +499,11 @@ Bucket.prototype.makePublic = function(options, callback) {
 };
 
 /**
- * Make the bucket listing private.
+ * Make the bucket publicly readable.
  *
- * You may also choose to make the contents of the bucket private by specifying
- * `includeFiles: true`. This will automatically run
- * {module:storage/file#makePrivate} for every file in the bucket.
+ * You may also choose to make the contents of the bucket publicly readable by
+ * specifying `includeFiles: true`. This will automatically run
+ * {module:storage/file#makePublic} for every file in the bucket.
  *
  * When specifying `includeFiles: true`, use `force: true` to delay execution of
  * your callback until all files have been processed. By default, the callback
@@ -527,51 +515,51 @@ Bucket.prototype.makePublic = function(options, callback) {
  * requests. Use with caution.
  *
  * @param {object=} options - The configuration object.
- * @param {boolean} options.includeFiles - Make each file in the bucket private.
- *     Default: `false`.
+ * @param {boolean} options.includeFiles - Make each file in the bucket publicly
+ *     readable. Default: `false`.
  * @param {boolean} options.force - Queue errors occurred while making files
- *     private until all files have been processed.
+ *     public until all files have been processed.
  * @param {function} callback - The callback function.
  *
  * @example
  * //-
- * // Make the bucket private.
+ * // Make the bucket publicly readable.
  * //-
- * bucket.makePrivate(function(err) {});
+ * bucket.makePublic(function(err) {});
  *
  * //-
- * // Make the bucket and its contents private.
+ * // Make the bucket and its contents publicly readable.
  * //-
  * var opts = {
  *   includeFiles: true
  * };
  *
- * bucket.makePrivate(opts, function(err, files) {
+ * bucket.makePublic(opts, function(err, files) {
  *   // `err`:
  *   //    The first error to occur, otherwise null.
  *   //
  *   // `files`:
- *   //    Array of files successfully made private in the bucket.
+ *   //    Array of files successfully made public in the bucket.
  * });
  *
  * //-
- * // Make the bucket and its contents private, using force to suppress errors
- * // until all files have been processed.
+ * // Make the bucket and its contents publicly readable, using force to
+ * // suppress errors until all files have been processed.
  * //-
  * var opts = {
  *   includeFiles: true,
  *   force: true
  * };
  *
- * bucket.makePrivate(opts, function(errors, files) {
+ * bucket.makePublic(opts, function(errors, files) {
  *   // `errors`:
  *   //    Array of errors if any occurred, otherwise null.
  *   //
  *   // `files`:
- *   //    Array of files successfully made private in the bucket.
+ *   //    Array of files successfully made public in the bucket.
  * });
  */
-Bucket.prototype.makePrivate = function(options, callback) {
+Bucket.prototype.makePublic = function(options, callback) {
   var self = this;
 
   if (util.is(options, 'function')) {
@@ -580,15 +568,27 @@ Bucket.prototype.makePrivate = function(options, callback) {
   }
 
   options = options || {};
-  options.private = true;
+  options.public = true;
 
-  async.parallel([setPredefinedAcl, makeFilesPrivate], callback);
+  async.parallel([
+    setPredefinedAcl,
+    addAclPermissions,
+    makeFilesPublic
+  ], callback);
 
   function setPredefinedAcl(done) {
     self.setPredefinedAcl_(options, done);
   }
 
-  function makeFilesPrivate(done) {
+  function addAclPermissions(done) {
+    // Allow reading bucket contents while preserving original permissions.
+    self.acl.default.add({
+      entity: 'allUsers',
+      role: 'READER'
+    }, done);
+  }
+
+  function makeFilesPublic(done) {
     if (!options.includeFiles) {
       done();
       return;
@@ -765,6 +765,23 @@ Bucket.prototype.upload = function(localPath, options, callback) {
   }
 };
 
+/**
+ * Iterate over all of a bucket's files, calling `file.makePublic()` (public)
+ * or `file.makePrivate()` (private) on each.
+ *
+ * Operations are performed in parallel, up to 10 at once. The first error
+ * breaks the loop, and will execute the provided callback with it. Specify
+ * `{ force: true }` to suppress the errors.
+ *
+ * @private
+ *
+ * @param {object} options - Configuration object.
+ * @param {boolean} options.force - Supress errors until all files have been
+ *     processed.
+ * @param {boolean} options.private - Make files private.
+ * @param {boolean} options.public - Make files public.
+ * @param {function} callback - The callback function.
+ */
 Bucket.prototype.makeAllFilesPublicPrivate_ = function(options, callback) {
   var self = this;
 
@@ -831,6 +848,18 @@ Bucket.prototype.makeAllFilesPublicPrivate_ = function(options, callback) {
   }
 };
 
+/**
+ * Set the predefinedAcl for this bucket to `publicRead` (public) or
+ * `projectPrivate` (private).
+ *
+ * This will also update the metadata on the object with the APIresponse.
+ *
+ * @private
+ *
+ * @param {object} options - Configuration object.
+ * @param {boolean} options.private - Set the predefinedAcl to projectPrivate.
+ * @param {boolean} options.public - Set the predefinedAcl to publicRead.
+ */
 Bucket.prototype.setPredefinedAcl_ = function(options, callback) {
   var self = this;