Fix and unify docs of bufread and read types.

- fix wrong docs of `bufread::GzDecoder`, `bufread::GzEncoder`, `bufread::MultiGzDecoder`
- make the types of inner reader and exported trait explicit.
- explicit state the pull model: user initialize the read, then data is
  read from the underlying stream.

src/deflate/bufread.rs

@@ -7,9 +7,10 @@ use crate::{Compress, Decompress};
 
 /// A DEFLATE encoder, or compressor.
 ///
-/// This structure consumes a [`BufRead`] interface, reading uncompressed data
-/// from the underlying reader, and emitting compressed data.
+/// This structure implements a [`Read`] interface. When read from, it reads
+/// uncompressed data from the underlying [`BufRead`] and provides the compressed data.
 ///
+/// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
 /// [`BufRead`]: https://doc.rust-lang.org/std/io/trait.BufRead.html
 ///
 /// # Examples
@@ -123,9 +124,10 @@ impl<W: BufRead + Write> Write for DeflateEncoder<W> {
 
 /// A DEFLATE decoder, or decompressor.
 ///
-/// This structure consumes a [`BufRead`] interface, reading compressed data
-/// from the underlying reader, and emitting uncompressed data.
+/// This structure implements a [`Read`] interface. When read from, it reads
+/// compressed data from the underlying [`BufRead`] and provides the uncompressed data.
 ///
+/// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
 /// [`BufRead`]: https://doc.rust-lang.org/std/io/trait.BufRead.html
 ///
 /// # Examples

src/deflate/read.rs

@@ -6,8 +6,8 @@ use crate::bufreader::BufReader;
 
 /// A DEFLATE encoder, or compressor.
 ///
-/// This structure implements a [`Read`] interface and will read uncompressed
-/// data from an underlying stream and emit a stream of compressed data.
+/// This structure implements a [`Read`] interface. When read from, it reads
+/// uncompressed data from the underlying [`Read`] and provides the compressed data.
 ///
 /// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
 ///
@@ -120,8 +120,8 @@ impl<W: Read + Write> Write for DeflateEncoder<W> {
 
 /// A DEFLATE decoder, or decompressor.
 ///
-/// This structure implements a [`Read`] interface and takes a stream of
-/// compressed data as input, providing the decompressed data when read from.
+/// This structure implements a [`Read`] interface. When read from, it reads
+/// compressed data from the underlying [`Read`] and provides the uncompressed data.
 ///
 /// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
 ///

src/gz/bufread.rs

@@ -19,10 +19,10 @@ fn copy(into: &mut [u8], from: &[u8], pos: &mut usize) -> usize {
 
 /// A gzip streaming encoder
 ///
-/// This structure exposes a [`BufRead`] interface that will read uncompressed data
-/// from the underlying reader and expose the compressed version as a [`BufRead`]
-/// interface.
+/// This structure implements a [`Read`] interface. When read from, it reads
+/// uncompressed data from the underlying [`BufRead`] and provides the compressed data.
 ///
+/// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
 /// [`BufRead`]: https://doc.rust-lang.org/std/io/trait.BufRead.html
 ///
 /// # Examples
@@ -165,8 +165,8 @@ impl<R: BufRead + Write> Write for GzEncoder<R> {
 
 /// 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.
+/// This structure implements a [`Read`] interface. When read from, it reads
+/// compressed data from the underlying [`BufRead`] and provides the uncompressed data.
 ///
 /// 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.
@@ -178,6 +178,7 @@ impl<R: BufRead + Write> Write for GzEncoder<R> {
 /// [in the introduction](../index.html#about-multi-member-gzip-files).
 ///
 /// [gzip file]: https://www.rfc-editor.org/rfc/rfc1952#page-5
+/// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
 /// [`BufRead`]: https://doc.rust-lang.org/std/io/trait.BufRead.html
 ///
 /// # Examples
@@ -351,8 +352,8 @@ impl<R: BufRead + Write> Write for GzDecoder<R> {
 
 /// A gzip streaming decoder that decodes a [gzip file] that may have multiple members.
 ///
-/// This structure exposes a [`BufRead`] interface that will consume compressed
-/// data from the underlying reader and emit uncompressed data.
+/// This structure implements a [`Read`] interface. When read from, it reads
+/// compressed data from the underlying [`BufRead`] and provides the uncompressed data.
 ///
 /// A gzip file consists of a series of *members* concatenated one after another.
 /// MultiGzDecoder decodes all members from the data and only returns Ok(0) when the
@@ -362,6 +363,7 @@ impl<R: BufRead + Write> Write for GzDecoder<R> {
 /// [in the introduction](../index.html#about-multi-member-gzip-files).
 ///
 /// [gzip file]: https://www.rfc-editor.org/rfc/rfc1952#page-5
+/// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
 /// [`BufRead`]: https://doc.rust-lang.org/std/io/trait.BufRead.html
 ///
 /// # Examples

src/gz/read.rs

@@ -8,9 +8,8 @@ use crate::Compression;
 
 /// A gzip streaming encoder
 ///
-/// This structure exposes a [`Read`] interface that will read uncompressed data
-/// from the underlying reader and expose the compressed version as a [`Read`]
-/// interface.
+/// This structure implements a [`Read`] interface. When read from, it reads
+/// uncompressed data from the underlying [`Read`] and provides the compressed data.
 ///
 /// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
 ///
@@ -92,8 +91,8 @@ impl<R: Read + Write> Write for GzEncoder<R> {
 
 /// A decoder for a single member of a [gzip file].
 ///
-/// This structure exposes a [`Read`] interface that will consume compressed
-/// data from the underlying reader and emit uncompressed data.
+/// This structure implements a [`Read`] interface. When read from, it reads
+/// compressed data from the underlying [`Read`] and provides the uncompressed data.
 ///
 /// 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.
@@ -201,8 +200,9 @@ impl<R: Read + Write> Write for GzDecoder<R> {
 
 /// A gzip streaming decoder that decodes a [gzip file] that may have multiple members.
 ///
-/// This structure exposes a [`Read`] interface that will consume compressed
-/// data from the underlying reader and emit uncompressed data.
+/// This structure implements a [`Read`] interface. When read from, it reads
+/// compressed data from the underlying [`Read`] and provides the 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

src/zlib/bufread.rs

@@ -7,9 +7,10 @@ use crate::{Compress, Decompress};
 
 /// A ZLIB encoder, or compressor.
 ///
-/// This structure consumes a [`BufRead`] interface, reading uncompressed data
-/// from the underlying reader, and emitting compressed data.
+/// This structure implements a [`Read`] interface. When read from, it reads
+/// uncompressed data from the underlying [`BufRead`] and provides the compressed data.
 ///
+/// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
 /// [`BufRead`]: https://doc.rust-lang.org/std/io/trait.BufRead.html
 ///
 /// # Examples
@@ -128,9 +129,10 @@ impl<R: BufRead + Write> Write for ZlibEncoder<R> {
 
 /// A ZLIB decoder, or decompressor.
 ///
-/// This structure consumes a [`BufRead`] interface, reading compressed data
-/// from the underlying reader, and emitting uncompressed data.
+/// This structure implements a [`Read`] interface. When read from, it reads
+/// compressed data from the underlying [`BufRead`] and provides the uncompressed data.
 ///
+/// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
 /// [`BufRead`]: https://doc.rust-lang.org/std/io/trait.BufRead.html
 ///
 /// # Examples

src/zlib/read.rs

@@ -7,8 +7,8 @@ use crate::Decompress;
 
 /// A ZLIB encoder, or compressor.
 ///
-/// This structure implements a [`Read`] interface and will read uncompressed
-/// data from an underlying stream and emit a stream of compressed data.
+/// This structure implements a [`Read`] interface. When read from, it reads
+/// uncompressed data from the underlying [`Read`] and provides the compressed data.
 ///
 /// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
 ///
@@ -126,8 +126,8 @@ impl<W: Read + Write> Write for ZlibEncoder<W> {
 
 /// A ZLIB decoder, or decompressor.
 ///
-/// This structure implements a [`Read`] interface and takes a stream of
-/// compressed data as input, providing the decompressed data when read from.
+/// This structure implements a [`Read`] interface. When read from, it reads
+/// compressed data from the underlying [`Read`] and provides the uncompressed data.
 ///
 /// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
 ///