From 7532260bb264ef231351d02877bb3268645a1804 Mon Sep 17 00:00:00 2001 From: Martin Algesten Date: Fri, 17 Jan 2025 09:41:39 +0100 Subject: [PATCH] ResponseExt doc improvements --- src/config.rs | 12 ++++++++---- src/response.rs | 40 ++++++++++++++++++++++++++++++++++++---- 2 files changed, 44 insertions(+), 8 deletions(-) diff --git a/src/config.rs b/src/config.rs index 874e4945..dd559973 100644 --- 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 ConfigBuilder { /// 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 index aa366efe..9a050e8b 100644 --- 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); -/// Extension trait for `http::Response` objects +/// Extension trait for [`http::Response`]. /// -/// 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::().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]>; }