Merge pull request #607 from ryanseys/set-metadata-mergy-docs

Update setMetadata docs to clarify merging. And whitespace issues

Author: ryanseys

lib/storage/file.js

@@ -1025,7 +1025,7 @@ File.prototype.getSignedPolicy = function(options, callback) {
  * @param {string=} options.responseDisposition - The
  *     response-content-disposition parameter (http://goo.gl/yMWxQV) of the
  *     signed url.
- * @param {string=} options.responseType - The response-content-type parameter 
+ * @param {string=} options.responseType - The response-content-type parameter
  *     of the signed url.
  * @param {function=} callback - The callback function.
  *
@@ -1071,20 +1071,20 @@ File.prototype.getSignedUrl = function(options, callback) {
 
     var responseContentType = '';
     if (util.is(options.responseType, 'string')) {
-      responseContentType = 
-        '&response-content-type=' + 
+      responseContentType =
+        '&response-content-type=' +
         encodeURIComponent(options.responseType);
     }
 
     var responseContentDisposition = '';
     if (util.is(options.promptSaveAs, 'string')) {
       responseContentDisposition =
-        '&response-content-disposition=attachment; filename="' + 
+        '&response-content-disposition=attachment; filename="' +
         encodeURIComponent(options.promptSaveAs) + '"';
     }
     if (util.is(options.responseDisposition, 'string')) {
-      responseContentDisposition = 
-        '&response-content-disposition=' + 
+      responseContentDisposition =
+        '&response-content-disposition=' +
         encodeURIComponent(options.responseDisposition);
     }
 
@@ -1100,9 +1100,17 @@ File.prototype.getSignedUrl = function(options, callback) {
 };
 
 /**
- * Set the file's metadata.
+ * Merge the given metadata with the current remote file's metadata. This will
+ * set metadata if it was previously unset or update previously set metadata. To
+ * unset previously set metadata, set its value to null.
+ *
+ * You can set custom key/value pairs in the metadata key of the given object,
+ * however the other properties outside of this object must adhere to the
+ * [official API documentation](https://goo.gl/BOnnCK).
  *
- * @param {object} metadata - The metadata you wish to set.
+ * See the examples below for more information.
+ *
+ * @param {object} metadata - The metadata you wish to update.
  * @param {function=} callback - The callback function.
  *
  * @example
@@ -1113,6 +1121,17 @@ File.prototype.getSignedUrl = function(options, callback) {
  *     properties: 'go here'
  *   }
  * }, function(err, metadata, apiResponse) {});
+ *
+ * // Assuming current metadata = { hello: 'world', unsetMe: 'will do' }
+ * file.setMetadata({
+ *   metadata: {
+ *     abc: '123', // will be set.
+ *     unsetMe: null, // will be unset (deleted).
+ *     hello: 'goodbye' // will be updated from 'hello' to 'goodbye'.
+ *   }
+ * }, function(err, metadata, apiResponse) {
+ *   // metadata should now be { abc: '123', hello: 'goodbye' }
+ * });
  */
 File.prototype.setMetadata = function(metadata, callback) {
   callback = callback || util.noop;