Make clear that most streams out there will typically not need MultiG…

…zDecoders

Make perfectly clear when to use which type.

Co-Authored-By: Josh Triplett <[email protected]>

src/gz/bufread.rs

@@ -401,7 +401,9 @@ impl<R: BufRead + Write> Write for GzDecoder<R> {
 ///
 /// A gzip file consists of a series of "members" concatenated one after another.
 /// MultiGzDecoder decodes all members of a file, while [GzDecoder] will only decode
-/// the first member. MultiGzDecoder is preferable in most cases.
+/// the first member. Many gzip files in the wild will typically have one member,
+/// but not all. Use MultiGzDecoder if you need to handle multiple members, or
+/// [GzDecoder] if you know you only need to handle a single member.
 ///
 /// This structure exposes a [`BufRead`] interface that will consume all gzip members
 /// from the underlying reader and emit uncompressed data.

src/gz/read.rs

@@ -182,8 +182,10 @@ impl<R: Read + Write> Write for GzDecoder<R> {
 ///
 /// A gzip file consists of a series of "members" concatenated one after another.
 /// MultiGzDecoder decodes all members of a file, while [GzDecoder] will only decode
-/// the first member. MultiGzDecoder is preferable in most cases.
-///
+/// the first member. Many gzip files in the wild will typically have one member,
+/// but not all. Use MultiGzDecoder if you need to handle multiple members, or
+/// [GzDecoder] if you know you only need to handle a single member.
+
 /// This structure exposes a [`Read`] interface that will consume all gzip members
 /// from the underlying reader and emit uncompressed data.
 ///

src/gz/write.rs

@@ -377,7 +377,9 @@ impl<W: Read + Write> Read for GzDecoder<W> {
 ///
 /// A gzip file consists of a series of "members" concatenated one after another.
 /// MultiGzDecoder decodes all members of a file, while [GzDecoder] will only decode
-/// the first member. MultiGzDecoder is preferable in most cases.
+/// the first member. Many gzip files in the wild will typically have one member,
+/// but not all. Use MultiGzDecoder if you need to handle multiple members, or
+/// [GzDecoder] if you know you only need to handle a single member.
 ///
 /// This structure exposes a [`Write`] interface that will consume all gzip members
 /// from the written buffers and write uncompressed data to the writer.