From 5b23cc91269c44165b07cbfee493d4aa353724fd Mon Sep 17 00:00:00 2001 From: Georeth Zhou Date: Sun, 10 Sep 2023 23:59:04 +0800 Subject: [PATCH] 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 | 10 ++++++---- src/deflate/read.rs | 8 ++++---- src/gz/bufread.rs | 16 +++++++++------- src/gz/read.rs | 14 +++++++------- src/zlib/bufread.rs | 10 ++++++---- src/zlib/read.rs | 8 ++++---- 6 files changed, 36 insertions(+), 30 deletions(-) diff --git a/src/deflate/bufread.rs b/src/deflate/bufread.rs index e375952d..c70a6303 100644 --- a/src/deflate/bufread.rs +++ b/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 Write for DeflateEncoder { /// 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 diff --git a/src/deflate/read.rs b/src/deflate/read.rs index 5937e6f6..2b6b8f2f 100644 --- a/src/deflate/read.rs +++ b/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 Write for DeflateEncoder { /// 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 /// diff --git a/src/gz/bufread.rs b/src/gz/bufread.rs index 6fc48bcd..679b4a7d 100644 --- a/src/gz/bufread.rs +++ b/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 Write for GzEncoder { /// 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 Write for GzEncoder { /// [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 Write for GzDecoder { /// 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 Write for GzDecoder { /// [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 diff --git a/src/gz/read.rs b/src/gz/read.rs index 5a65526c..9dbadbda 100644 --- a/src/gz/read.rs +++ b/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 Write for GzEncoder { /// 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 Write for GzDecoder { /// 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 diff --git a/src/zlib/bufread.rs b/src/zlib/bufread.rs index aa8af64f..85bbd38a 100644 --- a/src/zlib/bufread.rs +++ b/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 Write for ZlibEncoder { /// 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 diff --git a/src/zlib/read.rs b/src/zlib/read.rs index fbae7486..3b41ae6c 100644 --- a/src/zlib/read.rs +++ b/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 Write for ZlibEncoder { /// 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 ///