Improve doc for BodyWithConfig

src/body/mod.rs

@@ -247,7 +247,7 @@ impl Body {
     ///
     /// * Response is limited to 10MB.
     ///
-    /// To change this default use [`Body::as_reader()`] and deserialize JSON manually.
+    /// To change this default use [`Body::with_config()`].
     ///
     /// The returned value is something that derives [`Deserialize`](serde::Deserialize).
     /// You might need to be explicit with which type you want. See example below.
@@ -387,7 +387,7 @@ impl<'a> BodyWithConfig<'a> {
     ///
     /// The reader is either shared or owned, depending on `with_config` or `into_with_config`.
     ///
-    /// Consider:
+    /// ## Example of owned vs shared
     ///
     /// ```
     /// // Creates an owned reader.
@@ -417,6 +417,23 @@ impl<'a> BodyWithConfig<'a> {
     }
 
     /// Read into string.
+    ///
+    /// *Caution:* without a preceeding [`limit()`][BodyWithConfig::limit], this
+    /// becomes an unbounded sized `String`. A bad server could exhaust your memory.
+    ///
+    /// ## Example
+    ///
+    /// ```
+    /// // Reads max 10k to a String.
+    /// let string = ureq::get("https://httpbin.org/get")
+    ///     .call()?
+    ///     .body_mut()
+    ///     .with_config()
+    ///     // Important. Limits body to 10k
+    ///     .limit(10_000)
+    ///     .read_to_string()?;
+    /// # Ok::<_, ureq::Error>(())
+    /// ```
     pub fn read_to_string(self) -> Result<String, Error> {
         use std::io::Read;
         let mut reader = self.do_build();
@@ -426,6 +443,23 @@ impl<'a> BodyWithConfig<'a> {
     }
 
     /// Read into vector.
+    ///
+    /// *Caution:* without a preceeding [`limit()`][BodyWithConfig::limit], this
+    /// becomes an unbounded sized `Vec`. A bad server could exhaust your memory.
+    ///
+    /// ## Example
+    ///
+    /// ```
+    /// // Reads max 10k to a Vec.
+    /// let myvec = ureq::get("https://httpbin.org/get")
+    ///     .call()?
+    ///     .body_mut()
+    ///     .with_config()
+    ///     // Important. Limits body to 10k
+    ///     .limit(10_000)
+    ///     .read_to_vec()?;
+    /// # Ok::<_, ureq::Error>(())
+    /// ```
     pub fn read_to_vec(self) -> Result<Vec<u8>, Error> {
         use std::io::Read;
         let mut reader = self.do_build();
@@ -435,6 +469,25 @@ impl<'a> BodyWithConfig<'a> {
     }
 
     /// Read JSON body.
+    ///
+    /// *Caution:* without a preceeding [`limit()`][BodyWithConfig::limit], this
+    /// becomes an unbounded sized `String`. A bad server could exhaust your memory.
+    ///
+    /// ## Example
+    ///
+    /// ```
+    /// use serde_json::Value;
+    ///
+    /// // Reads max 10k as a JSON value.
+    /// let json: Value  = ureq::get("https://httpbin.org/get")
+    ///     .call()?
+    ///     .body_mut()
+    ///     .with_config()
+    ///     // Important. Limits body to 10k
+    ///     .limit(10_000)
+    ///     .read_json()?;
+    /// # Ok::<_, ureq::Error>(())
+    /// ```
     #[cfg(feature = "json")]
     pub fn read_json<T: serde::de::DeserializeOwned>(self) -> Result<T, Error> {
         let reader = self.do_build();