Add a warning to the storage/file#move method.

We should make it clear that this is a composition of two methods,
and if the second (storage/file#delete) were to fail,
a lingering file would be left around (which could cost money).

Fixes #544

lib/storage/file.js

@@ -235,10 +235,18 @@ File.prototype.copy = function(destination, callback) {
 };
 
 /**
- * Move this file to another location. By default, this will move 
- * the file to the same bucket, but you can choose to move it 
+ * Move this file to another location. By default, this will move
+ * the file to the same bucket, but you can choose to move it
  * to another Bucket by providing either a Bucket or File object.
  *
+ * **Warning**:
+ * There is currently no atomic `move` method in the Google Cloud Storage API,
+ * so this method is a composition of {module:storage/file#copy} (to the new
+ * location) and {module:storage/file#delete} (from the old location). While
+ * unlikely, it is possible that an error returned to your callback could be
+ * triggered from either one of these API calls failing, which could leave a
+ * duplicate file lingering.
+ *
  * @throws {Error} If the destination file is not provided.
  *
  * @param {string|module:storage/bucket|module:storage/file} destination -
@@ -265,7 +273,7 @@ File.prototype.copy = function(destination, callback) {
  *   // but contains instead:
  *   // - "my-image-new.png"
  *
- *   // `destinationFile` is an instance of a File object that refers 
+ *   // `destinationFile` is an instance of a File object that refers
  *   // to your new file.
  * });
  *
@@ -281,7 +289,7 @@ File.prototype.copy = function(destination, callback) {
  *   // `another-bucket` now contains:
  *   // - "my-image.png"
  *
- *   // `destinationFile` is an instance of a File object that refers 
+ *   // `destinationFile` is an instance of a File object that refers
  *   // to your new file.
  * });
  *