Issue #269: Add 'end' event documentation (#284)

Author: Nargonath

README.md

@@ -26,11 +26,19 @@ var archive = archiver('zip', {
 });
 
 // listen for all archive data to be written
+// 'close' event is fired only when a file descriptor is involved
 output.on('close', function() {
   console.log(archive.pointer() + ' total bytes');
   console.log('archiver has been finalized and the output file descriptor has closed.');
 });
 
+// This event is fired when the data source is drained no matter what was the data source.
+// It is not part of this library but rather from the NodeJS Stream API.
+// @see: https://nodejs.org/api/stream.html#stream_event_end
+output.on('end', function() {
+  console.log('Data has been drained');
+});
+
 // good practice to catch warnings (ie stat failures and other non-blocking errors)
 archive.on('warning', function(err) {
   if (err.code === 'ENOENT') {
@@ -73,6 +81,7 @@ archive.directory('subdir/', false);
 archive.glob('subdir/*.txt');
 
 // finalize the archive (ie we are done appending files but streams have to finish yet)
+// 'close', 'end' or 'finish' may be fired right after calling this method so register to them beforehand
 archive.finalize();
 ```
 
@@ -82,4 +91,4 @@ Archiver ships with out of the box support for TAR and ZIP archives.
 
 You can register additional formats with `registerFormat`.
 
-_Formats will be changing in the next few releases to implement a middleware approach._
+_Formats will be changing in the next few releases to implement a middleware approach._