Merge pull request #435 from stephenplusplus/spp--storage-document-complete-event

storage: explain `complete` event.

Author: ryanseys

lib/storage/file.js

@@ -227,6 +227,9 @@ File.prototype.copy = function(destination, callback) {
  * "CONTENT_DOWNLOAD_MISMATCH". If you receive this error, the best recourse is
  * to try downloading the file again.
  *
+ * NOTE: Readable streams will emit the `complete` event when the file is fully
+ * downloaded.
+ *
  * @param {object=} options - Configuration object.
  * @param {string|boolean} options.validation - Possible values: `"md5"`,
  *     `"crc32c"`, or `false`. By default, data integrity is validated with an
@@ -257,7 +260,10 @@ File.prototype.copy = function(destination, callback) {
  *
  * image.createReadStream()
  *   .pipe(fs.createWriteStream('/Users/stephen/Photos/image.png'))
- *   .on('error', function(err) {});
+ *   .on('error', function(err) {})
+ *   .on('complete', function() {
+ *     // The file is fully downloaded.
+ *   });
  *
  * //-
  * // To limit the downloaded data to only a byte range, pass an options object.
@@ -426,6 +432,9 @@ File.prototype.createReadStream = function(options) {
  *
  * A File object can also be used to create files for the first time.
  *
+ * NOTE: Writable streams will emit the `complete` event when the file is fully
+ * uploaded.
+ *
  * @param {object=} options - Configuration object.
  * @param {object=} options.metadata - Set the metadata for this file.
  * @param {boolean=} options.resumable - Force a resumable upload. NOTE: When
@@ -452,7 +461,10 @@ File.prototype.createReadStream = function(options) {
  *
  * fs.createReadStream('/Users/stephen/Photos/birthday-at-the-zoo/panda.jpg')
  *   .pipe(image.createWriteStream())
- *   .on('error', function(err) {});
+ *   .on('error', function(err) {})
+ *   .on('complete', function() {
+ *     // The file upload is complete.
+ *   });
  *
  * //-
  * // <h4>Uploading a File with Metadata</h4>