Merge pull request #347 from JohnTitor/note-to-multi-gz-decoder

src/gz/bufread.rs

@@ -171,6 +171,7 @@ impl<R: BufRead + Write> Write for GzEncoder<R> {
 ///
 /// This structure consumes a [`BufRead`] interface, reading compressed data
 /// from the underlying reader, and emitting uncompressed data.
+/// Use [`MultiGzDecoder`] if your file has multiple streams.
 ///
 /// [`BufRead`]: https://doc.rust-lang.org/std/io/trait.BufRead.html
 ///
@@ -401,9 +402,11 @@ impl<R: BufRead + Write> Write for GzDecoder<R> {
 /// A gzip member consists of a header, compressed data and a trailer. The [gzip
 /// specification](https://tools.ietf.org/html/rfc1952), however, allows multiple
 /// gzip members to be joined in a single stream. `MultiGzDecoder` will
-/// decode all consecutive members while `GzDecoder` will only decompress
+/// decode all consecutive members while [`GzDecoder`] will only decompress
 /// the first gzip member. The multistream format is commonly used in
-/// bioinformatics, for example when using the BGZF compressed data.
+/// bioinformatics, for example when using the BGZF compressed data. It's also useful
+/// to compress large amounts of data in parallel where each thread produces one stream
+/// for a chunk of input data.
 ///
 /// This structure exposes a [`BufRead`] interface that will consume all gzip members
 /// from the underlying reader and emit uncompressed data.

src/gz/read.rs

@@ -94,13 +94,13 @@ 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.
+/// Use [`MultiGzDecoder`] if your file has multiple streams.
 ///
 /// [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
 ///
 /// # Examples
 ///
 /// ```
-///
 /// use std::io::prelude::*;
 /// use std::io;
 /// # use flate2::Compression;
@@ -185,9 +185,11 @@ impl<R: Read + Write> Write for GzDecoder<R> {
 /// A gzip member consists of a header, compressed data and a trailer. The [gzip
 /// specification](https://tools.ietf.org/html/rfc1952), however, allows multiple
 /// gzip members to be joined in a single stream.  `MultiGzDecoder` will
-/// decode all consecutive members while `GzDecoder` will only decompress the
+/// decode all consecutive members while [`GzDecoder`] will only decompress the
 /// first gzip member. The multistream format is commonly used in bioinformatics,
-/// for example when using the BGZF compressed data.
+/// for example when using the BGZF compressed data. It's also useful
+/// to compress large amounts of data in parallel where each thread produces one stream
+/// for a chunk of input data.
 ///
 /// This structure exposes a [`Read`] interface that will consume all gzip members
 /// from the underlying reader and emit uncompressed data.

src/gz/write.rs

@@ -170,6 +170,7 @@ impl<W: Write> Drop for GzEncoder<W> {
 ///
 /// This structure exposes a [`Write`] interface that will emit uncompressed data
 /// to the underlying writer `W`.
+/// Use [`MultiGzDecoder`] if your file has multiple streams.
 ///
 /// [`Write`]: https://doc.rust-lang.org/std/io/trait.Write.html
 ///