update messagebody documentation

actix-http/CHANGES.md

@@ -1,12 +1,19 @@
 # Changes
 
 ## Unreleased - 2021-xx-xx
+### Added
+* New method on `MessageBody` trait, `try_into_bytes`, with default implementation, for optimizations on body types that complete in exactly one poll. Replaces `is_complete_body` and `take_complete_body`. [#2522]
+
 ### Changed
 * Rename trait `IntoHeaderPair => TryIntoHeaderPair`. [#2510]
 * Rename `TryIntoHeaderPair::{try_into_header_pair => try_into_pair}`. [#2510]
 * Rename trait `IntoHeaderValue => TryIntoHeaderValue`. [#2510]
 
+### Removed
+* `MessageBody::{is_complete_body,take_complete_body}`. [#2522]
+
 [#2510]: https://github.com/actix/actix-web/pull/2510
+[#2522]: https://github.com/actix/actix-web/pull/2522
 
 
 ## 3.0.0-beta.15 - 2021-12-11
@@ -27,7 +34,7 @@
 * `Request::take_conn_data()`. [#2491]
 * `Request::take_req_data()`. [#2487]
 * `impl Clone` for `RequestHead`. [#2487]
-* New methods on `MessageBody` trait, `is_complete_body` and `take_complete_body`, both with default implementations, for optimisations on body types that are done in exactly one poll/chunk. [#2497]
+* New methods on `MessageBody` trait, `is_complete_body` and `take_complete_body`, both with default implementations, for optimizations on body types that are done in exactly one poll/chunk. [#2497]
 * New `boxed` method on `MessageBody` trait for wrapping body type. [#2520]
 
 ### Changed

actix-http/src/body/message_body.rs

@@ -17,11 +17,15 @@ use super::{BodySize, BoxBody};
 /// An interface types that can converted to bytes and used as response bodies.
 // TODO: examples
 pub trait MessageBody {
-    // TODO: consider this bound to only fmt::Display since the error type is not really used
-    // and there is an impl for Into<Box<StdError>> on String
+    /// The type of error that will be returned if streaming body fails.
+    ///
+    /// Since it is not appropriate to generate a response mid-stream, it only requires `Error` for
+    /// internal use and logging.
     type Error: Into<Box<dyn StdError>>;
 
     /// Body size hint.
+    ///
+    /// If [`BodySize::None`] is returned, optimizations that skip reading the body are allowed.
     fn size(&self) -> BodySize;
 
     /// Attempt to pull out the next chunk of body bytes.
@@ -31,9 +35,17 @@ pub trait MessageBody {
         cx: &mut Context<'_>,
     ) -> Poll<Option<Result<Bytes, Self::Error>>>;
 
-    /// Convert this body into `Bytes`.
+    /// Try to convert into the complete chunk of body bytes.
     ///
-    /// Body types with `BodySize::None` are allowed to return empty `Bytes`.
+    /// Implement this method if the entire body can be trivially extracted. This is useful for
+    /// optimizations where `poll_next` calls can be avoided.
+    ///
+    /// Body types with [`BodySize::None`] are allowed to return empty `Bytes`. Although, if calling
+    /// this method, it is recommended to check `size` first and return early.
+    ///
+    /// # Errors
+    /// The default implementation will error and return the original type back to the caller for
+    /// further use.
     #[inline]
     fn try_into_bytes(self) -> Result<Bytes, Self>
     where

actix-http/src/response.rs

@@ -170,7 +170,7 @@ impl<B> Response<B> {
     /// Returns split head and body.
     ///
     /// # Implementation Notes
-    /// Due to internal performance optimisations, the first element of the returned tuple is a
+    /// Due to internal performance optimizations, the first element of the returned tuple is a
     /// `Response` as well but only contains the head of the response this was called on.
     pub fn into_parts(self) -> (Response<()>, B) {
         self.replace_body(())