Apply suggestions from code review

Co-authored-by: jongiddy <[email protected]>

src/gz/bufread.rs

@@ -167,15 +167,14 @@ impl<R: BufRead + Write> Write for GzEncoder<R> {
     }
 }
 
-/// A decoder for the first member of a [gzip file].
+/// A decoder for a single member of a [gzip file].
 ///
 /// This structure exposes a [`BufRead`] interface, reading compressed data
 /// from the underlying reader, and emitting uncompressed data.
 ///
-/// After reading the first member of a gzip file (which is often, but not
-/// always, the only member), this reader will return Ok(0) even if there
-/// are more bytes available in the underlying reader. If you want to be sure
-/// not to drop bytes on the floor, call `into_inner()` after Ok(0) to
+/// After reading a single member of the gzip data this reader will return 
+/// Ok(0) even if there are more bytes available in the underlying reader. 
+/// If you need the following bytes, call `into_inner()` after Ok(0) to
 /// recover the underlying reader.
 ///
 /// To handle gzip files that may have multiple members, see [`MultiGzDecoder`]
@@ -413,8 +412,8 @@ impl<R: BufRead + Write> Write for GzDecoder<R> {
 /// data from the underlying reader and emit uncompressed data.
 ///
 /// A gzip file consists of a series of *members* concatenated one after another.
-/// MultiGzDecoder decodes all members of a file and returns Ok(0) once the
-/// underlying reader does.
+/// MultiGzDecoder decodes all members from the data and only returns Ok(0) when the
+/// underlying reader does. For a file, this reads to the end of the file.
 ///
 /// To handle members seperately, see [GzDecoder] or read more
 /// [in the introduction](../index.html#about-multi-member-gzip-files).

src/gz/read.rs

@@ -95,11 +95,11 @@ impl<R: Read + Write> Write for GzEncoder<R> {
 /// This structure exposes a [`Read`] interface that will consume compressed
 /// data from the underlying reader and emit uncompressed data.
 ///
-/// After reading the first member of a gzip file (which is often, but not
-/// always, the only member), this reader will return Ok(0) even if there
-/// are more bytes available in the underlying reader. If you want to be sure
-/// not to drop bytes on the floor, call `into_inner()` after Ok(0) to
-/// recover the underlying reader.
+/// After reading a single member of the gzip data this reader will return
+/// Ok(0) even if there are more bytes available in the underlying reader.
+/// `GzDecoder` may have read additional bytes past the end of the gzip data.
+/// If you need the following bytes, wrap the `Reader` in a `std::io::BufReader` 
+/// and use `bufread::GzDecoder` instead.
 ///
 /// To handle gzip files that may have multiple members, see [`MultiGzDecoder`]
 /// or read more

src/gz/write.rs

@@ -166,13 +166,14 @@ impl<W: Write> Drop for GzEncoder<W> {
     }
 }
 
-/// A decoder for the first member of a [gzip file].
+/// A decoder for a single member of a [gzip file].
 ///
 /// This structure exposes a [`Write`] interface, receiving compressed data and
 /// writing uncompressed data to the underlying writer.
 ///
-/// After decoding the first member of a gzip file, this writer will return XXX
-/// to all subsequent writes.
+/// After decoding a single member of the gzip data this writer will return the number of bytes up to 
+/// to the end of the gzip member and subsequent writes will return Ok(0) allowing the caller to 
+/// handle any data following the gzip member.
 ///
 /// To handle gzip files that may have multiple members, see [`MultiGzDecoder`]
 /// or read more

src/lib.rs

@@ -70,8 +70,10 @@
 //! While most `gzip` files one encounters will have a single *member* that can be read
 //! with the [`GzDecoder`], there may be some files which have multiple members.
 //!
-//! If these are read with a [`GzDecoder`], only the first member will be consumed and
-//! the rest will silently be left alone, which can be surprising.
+//! A [`GzDecoder`] will only read the first member of gzip data, which may unexpectedly 
+//! provide partial results when a multi-member gzip file is encountered. `GzDecoder` is appropriate 
+//! for data that is designed to be read as single members from a multi-member file. `bufread::GzDecoder`
+//! and `write::GzDecoder` also allow non-gzip data following gzip data to be handled.
 //!
 //! The [`MultiGzDecoder`] on the other hand will decode all members of a `gzip` file
 //! into one consecutive stream of bytes, which hides the underlying *members* entirely.