ResponseExt doc improvements

algesten · Jan 17, 2025 · 7532260 · 7532260
1 parent c22ed8d
commit 7532260
Show file tree

Hide file tree

Showing 2 changed files with 44 additions and 8 deletions.
diff --git a/src/config.rs b/src/config.rs
@@ -281,10 +281,12 @@ impl Config {
     /// If we should record a history of every redirect location,
     /// including the request and final locations.
     ///
-    /// Comes at the cost of allocating/retaining the Uri for
+    /// Comes at the cost of allocating/retaining the `Uri` for
     /// every redirect loop.
     ///
-    /// Defaults to false
+    /// See [`ResponseExt::get_redirect_history()`][crate::ResponseExt::get_redirect_history].
+    ///
+    /// Defaults to `false`.
     pub fn save_redirect_history(&self) -> bool {
         self.save_redirect_history
     }
@@ -497,10 +499,12 @@ impl<Scope: private::ConfigScope> ConfigBuilder<Scope> {
     /// If we should record a history of every redirect location,
     /// including the request and final locations.
     ///
-    /// Comes at the cost of allocating/retaining the Uri for
+    /// Comes at the cost of allocating/retaining the `Uri` for
     /// every redirect loop.
     ///
-    /// Defaults to false
+    /// See [`ResponseExt::get_redirect_history()`][crate::ResponseExt::get_redirect_history].
+    ///
+    /// Defaults to `false`.
     pub fn save_redirect_history(mut self, v: bool) -> Self {
         self.config().save_redirect_history = v;
         self

diff --git a/src/response.rs b/src/response.rs
@@ -9,16 +9,48 @@ pub(crate) struct ResponseUri(pub http::Uri);
 #[derive(Debug, Clone)]
 pub(crate) struct RedirectHistory(pub Vec<Uri>);
 
-/// Extension trait for `http::Response<Body>` objects
+/// Extension trait for [`http::Response<Body>`].
 ///
-/// Allows the user to access the `Uri` in http::Response
+/// Adds additional convenience methods to the `Response` that are not available
+/// in the plain http API.
 pub trait ResponseExt {
-    /// The Uri we ended up at. This can differ from the request uri when we have followed redirects.
+    /// The Uri that ultimately this Response is about.
+    ///
+    /// This can differ from the request uri when we have followed redirects.
+    ///
+    /// ```
+    /// use ureq::ResponseExt;
+    ///
+    /// let res = ureq::get("https://httpbin.org/redirect-to?url=%2Fget")
+    ///     .call().unwrap();
+    ///
+    /// assert_eq!(res.get_uri(), "https://httpbin.org/get");
+    /// ```
     fn get_uri(&self) -> &Uri;
 
     /// The full history of uris, including the request and final uri.
     ///
-    /// Returns None when `save_redirect_history` is false.
+    /// Returns `None` when [`Config::save_redirect_history`][crate::config::Config::save_redirect_history]
+    /// is `false`.
+    ///
+    ///
+    /// ```
+    /// # use ureq::http::Uri;
+    /// use ureq::ResponseExt;
+    ///
+    /// let uri1: Uri = "https://httpbin.org/redirect-to?url=%2Fget".parse().unwrap();
+    /// let uri2: Uri = "https://httpbin.org/get".parse::<Uri>().unwrap();
+    ///
+    /// let res = ureq::get(&uri1)
+    ///     .config()
+    ///     .save_redirect_history(true)
+    ///     .build()
+    ///     .call().unwrap();
+    ///
+    /// let history = res.get_redirect_history().unwrap();
+    ///
+    /// assert_eq!(history, &[uri1, uri2]);
+    /// ```
     fn get_redirect_history(&self) -> Option<&[Uri]>;
 }