Merge pull request #558 from rust-lang/lib-doc-update

Update `get_mut()` documentation to make clear how 'inner` can be used

Author: Byron

src/deflate/bufread.rs

@@ -78,8 +78,11 @@ impl<R> DeflateEncoder<R> {
 
     /// Acquires a mutable reference to the underlying stream
     ///
-    /// Note that mutation of the stream may result in surprising results if
-    /// this encoder is continued to be used.
+    /// The underlying reader may be mutated as long as its unread input and
+    /// current position are preserved for subsequent reads by this encoder.
+    ///
+    /// To process a new stream, wait for this encoder to reach EOF and use
+    /// [`reset`](Self::reset); replacing the reader directly does not reset it.
     pub fn get_mut(&mut self) -> &mut R {
         &mut self.obj
     }
@@ -208,8 +211,11 @@ impl<R> DeflateDecoder<R> {
 
     /// Acquires a mutable reference to the underlying stream
     ///
-    /// Note that mutation of the stream may result in surprising results if
-    /// this decoder is continued to be used.
+    /// The underlying reader may be mutated as long as its unread input and
+    /// current position are preserved for subsequent reads by this decoder.
+    ///
+    /// To process a new stream, wait for this decoder to reach EOF and use
+    /// [`reset`](Self::reset); replacing the reader directly does not reset it.
     pub fn get_mut(&mut self) -> &mut R {
         &mut self.obj
     }

src/deflate/read.rs

@@ -71,8 +71,11 @@ impl<R> DeflateEncoder<R> {
 
     /// Acquires a mutable reference to the underlying stream
     ///
-    /// Note that mutation of the stream may result in surprising results if
-    /// this encoder is continued to be used.
+    /// The underlying reader may be mutated as long as its unread input and
+    /// current position are preserved for subsequent reads by this encoder.
+    ///
+    /// To process a new stream, wait for this encoder to reach EOF and use
+    /// [`reset`](Self::reset); replacing the reader directly does not reset it.
     pub fn get_mut(&mut self) -> &mut R {
         self.inner.get_mut().get_mut()
     }
@@ -202,8 +205,11 @@ impl<R> DeflateDecoder<R> {
 
     /// Acquires a mutable reference to the underlying stream
     ///
-    /// Note that mutation of the stream may result in surprising results if
-    /// this decoder is continued to be used.
+    /// The underlying reader may be mutated as long as its unread input and
+    /// current position are preserved for subsequent reads by this decoder.
+    ///
+    /// To process a new stream, wait for this decoder to reach EOF and use
+    /// [`reset`](Self::reset); replacing the reader directly does not reset it.
     pub fn get_mut(&mut self) -> &mut R {
         self.inner.get_mut().get_mut()
     }

src/deflate/write.rs

@@ -50,8 +50,18 @@ impl<W: Write> DeflateEncoder<W> {
 
     /// Acquires a mutable reference to the underlying writer.
     ///
-    /// Note that mutating the output/input state of the stream may corrupt this
-    /// object, so care must be taken when using this method.
+    /// The underlying writer may be mutated or replaced as long as this
+    /// preserves the bytes and ordering of the logical output stream.
+    /// Concatenate output from each writer to reconstruct the complete stream.
+    ///
+    /// Replacing the writer does not require [`flush`](Write::flush). Call it
+    /// first when all input accepted so far must be decodable without output
+    /// from later writes. This inserts a sync-flush point and changes the output
+    /// bitstream. This is useful before applying [`std::mem::take`] to
+    /// [`get_mut`](Self::get_mut) when forwarding the stream incrementally.
+    ///
+    /// To start a new stream, use [`reset`](Self::reset); replacing the writer
+    /// does not reset this encoder.
     pub fn get_mut(&mut self) -> &mut W {
         self.inner.get_mut()
     }
@@ -227,8 +237,17 @@ impl<W: Write> DeflateDecoder<W> {
 
     /// Acquires a mutable reference to the underlying writer.
     ///
-    /// Note that mutating the output/input state of the stream may corrupt this
-    /// object, so care must be taken when using this method.
+    /// The underlying writer may be mutated or replaced as long as this
+    /// preserves the bytes and ordering of the logical output stream.
+    /// Concatenate output from each writer to reconstruct the complete stream.
+    ///
+    /// Replacing the writer does not require [`flush`](Write::flush). Call it
+    /// first to write all decompressed output currently available to the
+    /// current writer. This is useful before applying [`std::mem::take`] to
+    /// [`get_mut`](Self::get_mut) when forwarding output incrementally.
+    ///
+    /// To start a new stream, use [`reset`](Self::reset); replacing the writer
+    /// does not reset this decoder.
     pub fn get_mut(&mut self) -> &mut W {
         self.inner.get_mut()
     }

src/gz/bufread.rs

@@ -104,8 +104,11 @@ impl<R> GzEncoder<R> {
 
     /// Acquires a mutable reference to the underlying reader.
     ///
-    /// Note that mutation of the reader may result in surprising results if
-    /// this encoder is continued to be used.
+    /// The underlying reader may be mutated as long as its unread input and
+    /// current position are preserved for subsequent reads by this encoder.
+    ///
+    /// To process a new stream, wait for this encoder to reach EOF and create a
+    /// new encoder; replacing the reader directly does not reset it.
     pub fn get_mut(&mut self) -> &mut R {
         self.inner.get_mut().get_mut()
     }
@@ -273,8 +276,11 @@ impl<R> GzDecoder<R> {
 
     /// Acquires a mutable reference to the underlying stream.
     ///
-    /// Note that mutation of the stream may result in surprising results if
-    /// this decoder is continued to be used.
+    /// The underlying reader may be mutated as long as its unread input and
+    /// current position are preserved for subsequent reads by this decoder.
+    ///
+    /// To process a new stream, wait for this decoder to reach EOF and use
+    /// [`reset`](Self::reset); replacing the reader directly does not reset it.
     pub fn get_mut(&mut self) -> &mut R {
         self.reader.get_mut().get_mut()
     }
@@ -435,8 +441,11 @@ impl<R> MultiGzDecoder<R> {
 
     /// Acquires a mutable reference to the underlying stream.
     ///
-    /// Note that mutation of the stream may result in surprising results if
-    /// this decoder is continued to be used.
+    /// The underlying reader may be mutated as long as its unread input and
+    /// current position are preserved for subsequent reads by this decoder.
+    ///
+    /// To process a new stream, wait for this decoder to reach EOF and create a
+    /// new decoder; replacing the reader directly does not reset it.
     pub fn get_mut(&mut self) -> &mut R {
         self.0.get_mut()
     }

src/gz/read.rs

@@ -61,8 +61,11 @@ impl<R> GzEncoder<R> {
 
     /// Acquires a mutable reference to the underlying reader.
     ///
-    /// Note that mutation of the reader may result in surprising results if
-    /// this encoder is continued to be used.
+    /// The underlying reader may be mutated as long as its unread input and
+    /// current position are preserved for subsequent reads by this encoder.
+    ///
+    /// To process a new stream, wait for this encoder to reach EOF and create a
+    /// new encoder; replacing the reader directly does not reset it.
     pub fn get_mut(&mut self) -> &mut R {
         self.inner.get_mut().get_mut()
     }
@@ -163,8 +166,11 @@ impl<R> GzDecoder<R> {
 
     /// Acquires a mutable reference to the underlying stream.
     ///
-    /// Note that mutation of the stream may result in surprising results if
-    /// this decoder continues to be used.
+    /// The underlying reader may be mutated as long as its unread input and
+    /// current position are preserved for subsequent reads by this decoder.
+    ///
+    /// To process a new stream, wait for this decoder to reach EOF and use
+    /// [`reset`](Self::reset); replacing the reader directly does not reset it.
     ///
     /// Note that the decoder may have read past the end of the gzip data.
     /// To prevent this use [`bufread::GzDecoder`] instead.
@@ -283,8 +289,11 @@ impl<R> MultiGzDecoder<R> {
 
     /// Acquires a mutable reference to the underlying stream.
     ///
-    /// Note that mutation of the stream may result in surprising results if
-    /// this decoder is continued to be used.
+    /// The underlying reader may be mutated as long as its unread input and
+    /// current position are preserved for subsequent reads by this decoder.
+    ///
+    /// To process a new stream, wait for this decoder to reach EOF and create a
+    /// new decoder; replacing the reader directly does not reset it.
     pub fn get_mut(&mut self) -> &mut R {
         self.inner.get_mut().get_mut()
     }

src/gz/write.rs

@@ -78,8 +78,18 @@ impl<W: Write> GzEncoder<W> {
 
     /// Acquires a mutable reference to the underlying writer.
     ///
-    /// Note that mutation of the writer may result in surprising results if
-    /// this encoder is continued to be used.
+    /// The underlying writer may be mutated or replaced as long as this
+    /// preserves the bytes and ordering of the logical output stream.
+    /// Concatenate output from each writer to reconstruct the complete stream.
+    ///
+    /// Replacing the writer does not require [`flush`](Write::flush). Call it
+    /// first when all input accepted so far must be decodable without output
+    /// from later writes. This inserts a sync-flush point and changes the output
+    /// bitstream. This is useful before applying [`std::mem::take`] to
+    /// [`get_mut`](Self::get_mut) when forwarding the stream incrementally.
+    ///
+    /// To start a new stream, call [`finish`](Self::finish) and create a new
+    /// encoder; replacing the writer does not reset it.
     pub fn get_mut(&mut self) -> &mut W {
         self.inner.get_mut()
     }
@@ -254,8 +264,17 @@ impl<W: Write> GzDecoder<W> {
 
     /// Acquires a mutable reference to the underlying writer.
     ///
-    /// Note that mutating the output/input state of the stream may corrupt this
-    /// object, so care must be taken when using this method.
+    /// The underlying writer may be mutated or replaced as long as this
+    /// preserves the bytes and ordering of the logical output stream.
+    /// Concatenate output from each writer to reconstruct the complete stream.
+    ///
+    /// Replacing the writer does not require [`flush`](Write::flush). Call it
+    /// first to write all decompressed output currently available to the
+    /// current writer. This is useful before applying [`std::mem::take`] to
+    /// [`get_mut`](Self::get_mut) when forwarding output incrementally.
+    ///
+    /// To start a new stream, call [`finish`](Self::finish) and create a new
+    /// decoder; replacing the writer does not reset it.
     pub fn get_mut(&mut self) -> &mut W {
         self.inner.get_mut().get_mut()
     }
@@ -408,8 +427,17 @@ impl<W: Write> MultiGzDecoder<W> {
 
     /// Acquires a mutable reference to the underlying writer.
     ///
-    /// Note that mutating the output/input state of the stream may corrupt this
-    /// object, so care must be taken when using this method.
+    /// The underlying writer may be mutated or replaced as long as this
+    /// preserves the bytes and ordering of the logical output stream.
+    /// Concatenate output from each writer to reconstruct the complete stream.
+    ///
+    /// Replacing the writer does not require [`flush`](Write::flush). Call it
+    /// first to write all decompressed output currently available to the
+    /// current writer. This is useful before applying [`std::mem::take`] to
+    /// [`get_mut`](Self::get_mut) when forwarding output incrementally.
+    ///
+    /// To start a new stream, call [`finish`](Self::finish) and create a new
+    /// decoder; replacing the writer does not reset it.
     pub fn get_mut(&mut self) -> &mut W {
         self.inner.get_mut()
     }

src/zlib/bufread.rs

@@ -83,8 +83,11 @@ impl<R> ZlibEncoder<R> {
 
     /// Acquires a mutable reference to the underlying stream
     ///
-    /// Note that mutation of the stream may result in surprising results if
-    /// this encoder is continued to be used.
+    /// The underlying reader may be mutated as long as its unread input and
+    /// current position are preserved for subsequent reads by this encoder.
+    ///
+    /// To process a new stream, wait for this encoder to reach EOF and use
+    /// [`reset`](Self::reset); replacing the reader directly does not reset it.
     pub fn get_mut(&mut self) -> &mut R {
         &mut self.obj
     }
@@ -216,8 +219,11 @@ impl<R> ZlibDecoder<R> {
 
     /// Acquires a mutable reference to the underlying stream
     ///
-    /// Note that mutation of the stream may result in surprising results if
-    /// this decoder is continued to be used.
+    /// The underlying reader may be mutated as long as its unread input and
+    /// current position are preserved for subsequent reads by this decoder.
+    ///
+    /// To process a new stream, wait for this decoder to reach EOF and use
+    /// [`reset`](Self::reset); replacing the reader directly does not reset it.
     pub fn get_mut(&mut self) -> &mut R {
         &mut self.obj
     }

src/zlib/read.rs

@@ -77,8 +77,11 @@ impl<R> ZlibEncoder<R> {
 
     /// Acquires a mutable reference to the underlying stream
     ///
-    /// Note that mutation of the stream may result in surprising results if
-    /// this encoder is continued to be used.
+    /// The underlying reader may be mutated as long as its unread input and
+    /// current position are preserved for subsequent reads by this encoder.
+    ///
+    /// To process a new stream, wait for this encoder to reach EOF and use
+    /// [`reset`](Self::reset); replacing the reader directly does not reset it.
     pub fn get_mut(&mut self) -> &mut R {
         self.inner.get_mut().get_mut()
     }
@@ -236,8 +239,11 @@ impl<R> ZlibDecoder<R> {
 
     /// Acquires a mutable reference to the underlying stream
     ///
-    /// Note that mutation of the stream may result in surprising results if
-    /// this decoder is continued to be used.
+    /// The underlying reader may be mutated as long as its unread input and
+    /// current position are preserved for subsequent reads by this decoder.
+    ///
+    /// To process a new stream, wait for this decoder to reach EOF and use
+    /// [`reset`](Self::reset); replacing the reader directly does not reset it.
     pub fn get_mut(&mut self) -> &mut R {
         self.inner.get_mut().get_mut()
     }

src/zlib/write.rs

@@ -59,8 +59,18 @@ impl<W: Write> ZlibEncoder<W> {
 
     /// Acquires a mutable reference to the underlying writer.
     ///
-    /// Note that mutating the output/input state of the stream may corrupt this
-    /// object, so care must be taken when using this method.
+    /// The underlying writer may be mutated or replaced as long as this
+    /// preserves the bytes and ordering of the logical output stream.
+    /// Concatenate output from each writer to reconstruct the complete stream.
+    ///
+    /// Replacing the writer does not require [`flush`](Write::flush). Call it
+    /// first when all input accepted so far must be decodable without output
+    /// from later writes. This inserts a sync-flush point and changes the output
+    /// bitstream. This is useful before applying [`std::mem::take`] to
+    /// [`get_mut`](Self::get_mut) when forwarding the stream incrementally.
+    ///
+    /// To start a new stream, use [`reset`](Self::reset); replacing the writer
+    /// does not reset this encoder.
     pub fn get_mut(&mut self) -> &mut W {
         self.inner.get_mut()
     }
@@ -248,8 +258,17 @@ impl<W: Write> ZlibDecoder<W> {
 
     /// Acquires a mutable reference to the underlying writer.
     ///
-    /// Note that mutating the output/input state of the stream may corrupt this
-    /// object, so care must be taken when using this method.
+    /// The underlying writer may be mutated or replaced as long as this
+    /// preserves the bytes and ordering of the logical output stream.
+    /// Concatenate output from each writer to reconstruct the complete stream.
+    ///
+    /// Replacing the writer does not require [`flush`](Write::flush). Call it
+    /// first to write all decompressed output currently available to the
+    /// current writer. This is useful before applying [`std::mem::take`] to
+    /// [`get_mut`](Self::get_mut) when forwarding output incrementally.
+    ///
+    /// To start a new stream, use [`reset`](Self::reset); replacing the writer
+    /// does not reset this decoder.
     pub fn get_mut(&mut self) -> &mut W {
         self.inner.get_mut()
     }