docs: show how to use versioning

lib/storage/bucket.js

@@ -368,6 +368,16 @@ Bucket.prototype.file = function(name, options) {
  * bucket.getFiles({
  *   maxResults: 5
  * }, function(err, files, nextQuery, apiResponse) {});
+ *
+ * //-
+ * // If your bucket has versioning enabled, you can get all of your files
+ * // scoped to their generation.
+ * //-
+ * bucket.getFiles({
+ *   versions: true
+ * }, function(err, files, nextQuery, apiResponse) {
+ *   // Each file is scoped to its generation.
+ * });
  */
 Bucket.prototype.getFiles = function(query, callback) {
   var self = this;
@@ -652,6 +662,15 @@ Bucket.prototype.makePublic = function(options, callback) {
  *     notFoundPage: 'http://example.com/404.html'
  *   }
  * }, function(err, metadata, apiResponse) {});
+ *
+ * //-
+ * // Enable versioning for your bucket.
+ * //-
+ * bucket.setMetadata({
+ *   versioning: {
+ *     enabled: true
+ *   }
+ * }, function(err, metadata, apiResponse) {});
  */
 Bucket.prototype.setMetadata = function(metadata, callback) {
   var that = this;

lib/storage/file.js

@@ -54,9 +54,8 @@ var STORAGE_UPLOAD_BASE_URL = 'https://www.googleapis.com/upload/storage/v1/b';
  * @param {module:storage/bucket} bucket - The Bucket instance this file is
  *     attached to.
  * @param {string} name - The name of the remote file.
- * @param {object=} metadata - Metadata to set on the object. This is useful
- *     when you are creating a file for the first time, to prevent making an
- *     extra call to `setMetadata`.
+ * @param {object=} options - Configuration object.
+ * @param {number} options.generation - Generation to scope the file to.
  */
 /**
  * A File object is created from your Bucket object using

lib/storage/index.js

@@ -190,19 +190,31 @@ Storage.prototype.bucket = function(name) {
  * @param {function} callback - The callback function.
  *
  * @example
- * storage.createBucket('new-bucket', function(err, bucket, apiResponse) {
+ * var callback = function(err, bucket, apiResponse) {
  *   // `bucket` is a Bucket object.
- * });
+ * };
+ *
+ * storage.createBucket('new-bucket', callback);
  *
- * // Specifying metadata.
+ * //-
+ * // Specify metadata.
+ * //-
  * var metadata = {
  *   mainPageSuffix: '/unknown/',
  *   maxAgeSeconds: 90
  * };
  *
- * var callback = function(err, bucket, apiResponse) {
- *   // `bucket` is a Bucket object.
- * }
+ * storage.createBucket('new-bucket', metadata, callback);
+ *
+ * //-
+ * // Enable versioning on a new bucket.
+ * //-
+ * var metadata = {
+ *   versioning: {
+ *     enabled: true
+ *   }
+ * };
+ *
  * storage.createBucket('new-bucket', metadata, callback);
  */
 Storage.prototype.createBucket = function(name, metadata, callback) {