Merge pull request rust-lang#408 from marxin/document-read-after-end

docs: Document expected behavior when Read is done for ZLIB and DEFLATE decoders

Author: Byron

src/deflate/bufread.rs

@@ -127,6 +127,11 @@ impl<W: BufRead + Write> Write for DeflateEncoder<W> {
 /// 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 DEFLATE 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.
+///
 /// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
 /// [`BufRead`]: https://doc.rust-lang.org/std/io/trait.BufRead.html
 ///

src/deflate/read.rs

@@ -123,6 +123,12 @@ impl<W: Read + Write> Write for DeflateEncoder<W> {
 /// 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 DEFLATE data this reader will return
+/// Ok(0) even if there are more bytes available in the underlying reader.
+/// `DeflateDecoder` may have read additional bytes past the end of the DEFLATE data.
+/// If you need the following bytes, wrap the `Reader` in a `std::io::BufReader`
+/// and use `bufread::DeflateDecoder` instead.
+///
 /// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
 ///
 /// # Examples

src/deflate/write.rs

@@ -172,6 +172,10 @@ impl<W: Read + Write> Read for DeflateEncoder<W> {
 /// This structure implements a [`Write`] and will emit a stream of decompressed
 /// data when fed a stream of compressed data.
 ///
+/// After decoding a single member of the DEFLATE data this writer will return the number of bytes up to
+/// to the end of the DEFLATE member and subsequent writes will return Ok(0) allowing the caller to
+/// handle any data following the DEFLATE member.
+///
 /// [`Write`]: https://doc.rust-lang.org/std/io/trait.Read.html
 ///
 /// # Examples

src/zlib/bufread.rs

@@ -132,6 +132,11 @@ impl<R: BufRead + Write> Write for ZlibEncoder<R> {
 /// 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 ZLIB 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.
+///
 /// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
 /// [`BufRead`]: https://doc.rust-lang.org/std/io/trait.BufRead.html
 ///

src/zlib/read.rs

@@ -129,6 +129,12 @@ impl<W: Read + Write> Write for ZlibEncoder<W> {
 /// 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 ZLIB data this reader will return
+/// Ok(0) even if there are more bytes available in the underlying reader.
+/// `ZlibDecoder` may have read additional bytes past the end of the ZLIB data.
+/// If you need the following bytes, wrap the `Reader` in a `std::io::BufReader`
+/// and use `bufread::ZlibDecoder` instead.
+///
 /// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
 ///
 /// # Examples

src/zlib/write.rs

@@ -180,6 +180,10 @@ impl<W: Read + Write> Read for ZlibEncoder<W> {
 /// This structure implements a [`Write`] and will emit a stream of decompressed
 /// data when fed a stream of compressed data.
 ///
+/// After decoding a single member of the ZLIB data this writer will return the number of bytes up to
+/// to the end of the ZLIB member and subsequent writes will return Ok(0) allowing the caller to
+/// handle any data following the ZLIB member.
+///
 /// [`Write`]: https://doc.rust-lang.org/std/io/trait.Write.html
 ///
 /// # Examples