Improve documentation and error messages for `InputStream`.

Closes #196.

README.md

@@ -174,15 +174,27 @@ Zip::File.open('foo.zip') do |zip_file|
 end
 ```
 
-#### Notice about ::Zip::InputStream
+### Notes on `Zip::InputStream`
 
-`::Zip::InputStream` usable for fast reading zip file content because it not read Central directory.
+`Zip::InputStream` can be used for faster reading of zip file content because it does not read the Central directory up front.
 
-But there is one exception when it is not working - General Purpose Flag Bit 3.
+There is one exception where it can not work however, and this is if the file does not contain enough information in the local entry headers to extract an entry. This is indicated in an entry by the General Purpose Flag bit 3 being set.
 
-> If bit 3 (0x08) of the general-purpose flags field is set, then the CRC-32 and file sizes are not known when the header is written. The fields in the local header are filled with zero, and the CRC-32 and size are appended in a 12-byte structure (optionally preceded by a 4-byte signature) immediately after the compressed data
+> If bit 3 (0x08) of the general-purpose flags field is set, then the CRC-32 and file sizes are not known when the header is written. The fields in the local header are filled with zero, and the CRC-32 and size are appended in a 12-byte structure (optionally preceded by a 4-byte signature) immediately after the compressed data.
 
-If `::Zip::InputStream` finds such entry in the zip archive it will raise an exception.
+If `Zip::InputStream` finds such an entry in the zip archive it will raise an exception (`Zip::GPFBit3Error`).
+
+`Zip::InputStream` is not designed to be used for random access in a zip file. When performing any operations on an entry that you are accessing via `Zip::InputStream.get_next_entry` then you should complete any such operations before the next call to `get_next_entry`.
+
+```ruby
+zip_stream = Zip::InputStream.new(File.open('file.zip'))
+
+while entry = zip_stream.get_next_entry
+  # All required operations on `entry` go here.
+end
+```
+
+Any attempt to move about in a zip file opened with `Zip::InputStream` could result in the incorrect entry being accessed and/or Zlib buffer errors. If you need random access in a zip file, use `Zip::File`.
 
 ### Password Protection (Experimental)
 

lib/zip/inflater.rb

@@ -39,8 +39,9 @@ module Zip
         retried += 1
         retry
       end
-    rescue Zlib::Error
+    rescue Zlib::Error => e
-      raise(::Zip::DecompressionError, 'zlib error while inflating')
+      raise ::Zip::DecompressionError,
+            "Zlib error ('#{e.message}') while inflating"
     end
 
     def input_finished?