Merge pull request #14 from Nemo157/docs

Docs

Author: Nemo157

.travis.yml

@@ -1,6 +1,6 @@
 language: rust
 rust:
-  - nightly-2019-04-25
+  - nightly-2019-05-11
 
 before_script: |
   rustup component add rustfmt clippy

Cargo.toml

@@ -9,11 +9,12 @@ license = "MIT OR Apache-2.0"
 brotli2 = "0.3.2"
 bytes = "0.4.12"
 flate2 = "1.0.7"
-futures-preview = "0.3.0-alpha.15"
+futures-preview = "0.3.0-alpha.16"
 pin-project = "0.3.2"
 
 [dev-dependencies]
 proptest = "0.9.3"
 pin-utils = "0.1.0-alpha.4"
 proptest-derive = "0.1.1"
 rand = "0.6.5"
+futures-test-preview = "0.3.0-alpha.16"

src/read/deflate.rs src/bufread/deflate.rs

@@ -4,23 +4,38 @@ use core::{
 };
 use std::io::Result;
 
-pub use flate2::Compression;
-use flate2::{Compress, FlushCompress};
+use flate2::{Compress, Compression, FlushCompress};
 use futures::{
     io::{AsyncBufRead, AsyncRead},
     ready,
 };
 use pin_project::unsafe_project;
 
+/// A DEFLATE encoder, or compressor.
+///
+/// This structure implements an [`AsyncRead`] interface and will read uncompressed data from an
+/// underlying stream and emit a stream of compressed data.
 #[unsafe_project(Unpin)]
-pub struct DeflateRead<R: AsyncBufRead> {
+pub struct DeflateEncoder<R: AsyncBufRead> {
     #[pin]
     inner: R,
     flushing: bool,
     compress: Compress,
 }
 
-impl<R: AsyncBufRead> AsyncRead for DeflateRead<R> {
+impl<R: AsyncBufRead> DeflateEncoder<R> {
+    /// Creates a new encoder which will read uncompressed data from the given stream and emit a
+    /// compressed stream.
+    pub fn new(read: R, level: Compression) -> DeflateEncoder<R> {
+        DeflateEncoder {
+            inner: read,
+            flushing: false,
+            compress: Compress::new(level, false),
+        }
+    }
+}
+
+impl<R: AsyncBufRead> AsyncRead for DeflateEncoder<R> {
     fn poll_read(
         self: Pin<&mut Self>,
         cx: &mut Context<'_>,
@@ -50,13 +65,3 @@ impl<R: AsyncBufRead> AsyncRead for DeflateRead<R> {
         }
     }
 }
-
-impl<R: AsyncBufRead> DeflateRead<R> {
-    pub fn new(read: R, level: Compression) -> DeflateRead<R> {
-        DeflateRead {
-            inner: read,
-            flushing: false,
-            compress: Compress::new(level, false),
-        }
-    }
-}

src/bufread/mod.rs

@@ -0,0 +1,8 @@
+//! Types which operate over [`AsyncBufRead`](futures::io::AsyncBufRead) streams, both encoders and
+//! decoders for various formats.
+
+mod deflate;
+mod zlib;
+
+pub use deflate::DeflateEncoder;
+pub use zlib::ZlibEncoder;

src/read/zlib.rs src/bufread/zlib.rs

@@ -4,23 +4,38 @@ use core::{
 };
 use std::io::Result;
 
-pub use flate2::Compression;
-use flate2::{Compress, FlushCompress};
+use flate2::{Compress, Compression, FlushCompress};
 use futures::{
     io::{AsyncBufRead, AsyncRead},
     ready,
 };
 use pin_project::unsafe_project;
 
+/// A zlib encoder, or compressor.
+///
+/// This structure implements an [`AsyncRead`] interface and will read uncompressed data from an
+/// underlying stream and emit a stream of compressed data.
 #[unsafe_project(Unpin)]
-pub struct ZlibRead<R: AsyncBufRead> {
+pub struct ZlibEncoder<R: AsyncBufRead> {
     #[pin]
     inner: R,
     flushing: bool,
     compress: Compress,
 }
 
-impl<R: AsyncBufRead> AsyncRead for ZlibRead<R> {
+impl<R: AsyncBufRead> ZlibEncoder<R> {
+    /// Creates a new encoder which will read uncompressed data from the given stream and emit a
+    /// compressed stream.
+    pub fn new(read: R, level: Compression) -> ZlibEncoder<R> {
+        ZlibEncoder {
+            inner: read,
+            flushing: false,
+            compress: Compress::new(level, true),
+        }
+    }
+}
+
+impl<R: AsyncBufRead> AsyncRead for ZlibEncoder<R> {
     fn poll_read(
         self: Pin<&mut Self>,
         cx: &mut Context<'_>,
@@ -50,13 +65,3 @@ impl<R: AsyncBufRead> AsyncRead for ZlibRead<R> {
         }
     }
 }
-
-impl<R: AsyncBufRead> ZlibRead<R> {
-    pub fn new(read: R, level: Compression) -> ZlibRead<R> {
-        ZlibRead {
-            inner: read,
-            flushing: false,
-            compress: Compress::new(level, true),
-        }
-    }
-}

src/lib.rs

@@ -1,2 +1,27 @@
-pub mod read;
+//! Adaptors between compression crates and Rust's modern asynchronous IO types.
+//!
+//!
+//! # Organization
+//!
+//! This crate is divided up into a number of modules based on the underlying asynchronous IO type
+//! that will be wrapped:
+//!
+//!  * [`bufread`] provides types which operate over [`AsyncBufRead`](futures::io::AsyncBufRead)
+//!    streams
+//!  * [`stream`] provides types which operate over [`Stream`](futures::stream::Stream)`<Item =
+//!    `[`io::Result`](std::io::Result)`<`[`Bytes`](bytes::Bytes)`>>` streams
+
+#![warn(missing_docs)]
+
+pub mod bufread;
 pub mod stream;
+
+/// Types to configure [`flate2`](::flate2) based encoders.
+pub mod flate2 {
+    pub use flate2::Compression;
+}
+
+/// Types to configure [`brotli2`](::brotli2) based encoders.
+pub mod brotli2 {
+    pub use brotli2::CompressParams;
+}

src/read/brotli.rs

@@ -4,21 +4,74 @@ use core::{
 };
 use std::io::{Error, ErrorKind, Result};
 
-use brotli2::raw::{CoStatus, CompressOp, DeStatus, Decompress};
-pub use brotli2::{raw::Compress, CompressParams};
+use brotli2::{
+    raw::{CoStatus, Compress, CompressOp, DeStatus, Decompress},
+    CompressParams,
+};
 use bytes::{Bytes, BytesMut};
 use futures::{ready, stream::Stream};
 use pin_project::unsafe_project;
 
+/// A brotli encoder, or compressor.
+///
+/// This structure implements a [`Stream`] interface and will read uncompressed data from an
+/// underlying stream and emit a stream of compressed data.
 #[unsafe_project(Unpin)]
-pub struct BrotliStream<S: Stream<Item = Result<Bytes>>> {
+pub struct BrotliEncoder<S: Stream<Item = Result<Bytes>>> {
     #[pin]
     inner: S,
     flush: bool,
     compress: Compress,
 }
 
-impl<S: Stream<Item = Result<Bytes>>> Stream for BrotliStream<S> {
+/// A brotli decoder, or decompressor.
+///
+/// This structure implements a [`Stream`] interface and will read compressed data from an
+/// underlying stream and emit a stream of uncompressed data.
+#[unsafe_project(Unpin)]
+pub struct BrotliDecoder<S: Stream<Item = Result<Bytes>>> {
+    #[pin]
+    inner: S,
+    flush: bool,
+    decompress: Decompress,
+}
+
+impl<S: Stream<Item = Result<Bytes>>> BrotliEncoder<S> {
+    /// Creates a new encoder which will read uncompressed data from the given stream and emit a
+    /// compressed stream.
+    ///
+    /// The `level` argument here is typically 0-11.
+    pub fn new(stream: S, level: u32) -> BrotliEncoder<S> {
+        let mut params = CompressParams::new();
+        params.quality(level);
+        BrotliEncoder::from_params(stream, &params)
+    }
+
+    /// Creates a new encoder with a custom [`CompressParams`].
+    pub fn from_params(stream: S, params: &CompressParams) -> BrotliEncoder<S> {
+        let mut compress = Compress::new();
+        compress.set_params(params);
+        BrotliEncoder {
+            inner: stream,
+            flush: false,
+            compress,
+        }
+    }
+}
+
+impl<S: Stream<Item = Result<Bytes>>> BrotliDecoder<S> {
+    /// Creates a new decoder which will read compressed data from the given stream and emit an
+    /// uncompressed stream.
+    pub fn new(stream: S) -> BrotliDecoder<S> {
+        BrotliDecoder {
+            inner: stream,
+            flush: false,
+            decompress: Decompress::new(),
+        }
+    }
+}
+
+impl<S: Stream<Item = Result<Bytes>>> Stream for BrotliEncoder<S> {
     type Item = Result<Bytes>;
 
     fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Result<Bytes>>> {
@@ -63,25 +116,7 @@ impl<S: Stream<Item = Result<Bytes>>> Stream for BrotliStream<S> {
     }
 }
 
-impl<S: Stream<Item = Result<Bytes>>> BrotliStream<S> {
-    pub fn new(stream: S, compress: Compress) -> BrotliStream<S> {
-        BrotliStream {
-            inner: stream,
-            flush: false,
-            compress,
-        }
-    }
-}
-
-#[unsafe_project(Unpin)]
-pub struct DecompressedBrotliStream<S: Stream<Item = Result<Bytes>>> {
-    #[pin]
-    inner: S,
-    flush: bool,
-    decompress: Decompress,
-}
-
-impl<S: Stream<Item = Result<Bytes>>> Stream for DecompressedBrotliStream<S> {
+impl<S: Stream<Item = Result<Bytes>>> Stream for BrotliDecoder<S> {
     type Item = Result<Bytes>;
 
     fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Result<Bytes>>> {
@@ -126,13 +161,3 @@ impl<S: Stream<Item = Result<Bytes>>> Stream for DecompressedBrotliStream<S> {
         Poll::Ready(Some(Ok(decompressed_output.freeze())))
     }
 }
-
-impl<S: Stream<Item = Result<Bytes>>> DecompressedBrotliStream<S> {
-    pub fn new(stream: S) -> DecompressedBrotliStream<S> {
-        DecompressedBrotliStream {
-            inner: stream,
-            flush: false,
-            decompress: Decompress::new(),
-        }
-    }
-}