From cfa82147ec961354c6f714a91e0dacedcd830c94 Mon Sep 17 00:00:00 2001 From: Sebastian Thiel Date: Fri, 21 Jul 2023 08:38:51 +0200 Subject: [PATCH] Make clear that most streams out there will typically not need MultiGzDecoders Make perfectly clear when to use which type. Co-Authored-By: Josh Triplett --- src/gz/bufread.rs | 4 +++- src/gz/read.rs | 6 ++++-- src/gz/write.rs | 4 +++- 3 files changed, 10 insertions(+), 4 deletions(-) diff --git a/src/gz/bufread.rs b/src/gz/bufread.rs index 25bd74ac..aa393d6f 100644 --- a/src/gz/bufread.rs +++ b/src/gz/bufread.rs @@ -401,7 +401,9 @@ impl Write for GzDecoder { /// /// 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. diff --git a/src/gz/read.rs b/src/gz/read.rs index fbd34ccd..aaee3609 100644 --- a/src/gz/read.rs +++ b/src/gz/read.rs @@ -182,8 +182,10 @@ impl Write for GzDecoder { /// /// 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. /// diff --git a/src/gz/write.rs b/src/gz/write.rs index b2b7be5e..af71244b 100644 --- a/src/gz/write.rs +++ b/src/gz/write.rs @@ -377,7 +377,9 @@ impl Read for GzDecoder { /// /// 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.