Use ? instead of unwrap in examples (#458)

This is recommended by the Rust API Guidelines:

https://rust-lang.github.io/api-guidelines/documentation.html#examples-use--not-try-not-unwrap-c-question-mark

One exception: When we need to unwrap an Option, the examples still use
.unwrap(). The alternative would be something like
`.ok_or(SomeErrorHere)?`, which feels like an awkward way to deal with
an Option. This might get better with NoneError:

https://docs.rs/rustc-std-workspace-std/1.0.1/std/option/struct.NoneError.html

I also rearranged some examples that used turbofish to use type
annotations. I think type annotations are more familiar to early Rust
users (and they use fewer characters and less punctuation, which is
always nice).

src/agent.rs

@@ -157,7 +157,7 @@ impl Agent {
     /// use {url::Url, ureq::Response};
     /// let agent = ureq::agent();
     ///
-    /// let mut url: Url = "http://example.com/some-page".parse().unwrap();
+    /// let mut url: Url = "http://example.com/some-page".parse()?;
     /// url.set_path("/robots.txt");
     /// let resp: Response = agent
     ///     .request_url("GET", &url)
@@ -216,7 +216,7 @@ impl Agent {
     ///
     /// // Saves (persistent) cookies
     /// let mut file = File::create("cookies.json")?;
-    /// agent.cookie_store().save_json(&mut file).unwrap();
+    /// agent.cookie_store().save_json(&mut file)?;
     /// # Ok(())
     /// # }
     /// ```
@@ -550,7 +550,7 @@ impl AgentBuilder {
     /// # ureq::is_test(true);
     /// use std::sync::Arc;
     /// # #[cfg(feature = "native-tls")]
-    /// let tls_connector = Arc::new(native_tls::TlsConnector::new().unwrap());
+    /// let tls_connector = Arc::new(native_tls::TlsConnector::new()?);
     /// # #[cfg(feature = "native-tls")]
     /// let agent = ureq::builder()
     ///     .tls_connector(tls_connector.clone())
@@ -580,7 +580,7 @@ impl AgentBuilder {
     /// let read = BufReader::new(file);
     ///
     /// // Read persisted cookies from cookies.json
-    /// let my_store = CookieStore::load_json(read).unwrap();
+    /// let my_store = CookieStore::load_json(read)?;
     ///
     /// // Cookies will be used for requests done through agent.
     /// let agent = ureq::builder()

src/error.rs

@@ -116,6 +116,7 @@ impl Error {
 /// * [`Transport::source()`](std::error::Error::source) holds the underlying error with even more details.
 ///
 /// ```
+/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
 /// use ureq::ErrorKind;
 /// use std::error::Error;
 /// use url::ParseError;
@@ -137,9 +138,11 @@ impl Error {
 /// // boxed underlying error
 /// let source = error.source().unwrap();
 /// // downcast to original error
-/// let downcast = source.downcast_ref::<ParseError>().unwrap();
+/// let downcast: &ParseError = source.downcast_ref().unwrap();
 ///
 /// assert_eq!(downcast.to_string(), "relative URL without a base");
+/// # Ok(())
+/// # }
 /// ```
 #[derive(Debug)]
 pub struct Transport {

src/lib.rs

@@ -263,7 +263,7 @@
 //!   use ureq::Agent;
 //!
 //!   let agent = ureq::AgentBuilder::new()
-//!       .tls_connector(Arc::new(native_tls::TlsConnector::new().unwrap()))
+//!       .tls_connector(Arc::new(native_tls::TlsConnector::new()?))
 //!       .build();
 //! # Ok(())
 //! # }
@@ -487,7 +487,7 @@ pub fn request(method: &str, path: &str) -> Request {
 /// use url::Url;
 /// let agent = ureq::agent();
 ///
-/// let mut url: Url = "http://example.com/some-page".parse().unwrap();
+/// let mut url: Url = "http://example.com/some-page".parse()?;
 /// url.set_path("/robots.txt");
 /// let resp: ureq::Response = ureq::request_url("GET", &url)
 ///     .call()?;

src/request.rs

@@ -424,7 +424,7 @@ impl Request {
     /// let req = ureq::get("http://httpbin.org/get")
     ///     .query("foo", "bar");
     ///
-    /// assert_eq!(req.request_url().unwrap().host(), "httpbin.org");
+    /// assert_eq!(req.request_url()?.host(), "httpbin.org");
     /// # Ok(())
     /// # }
     /// ```
@@ -490,7 +490,7 @@ impl RequestUrl {
     ///     .query("foo", "42")
     ///     .query("foo", "43");
     ///
-    /// assert_eq!(req.request_url().unwrap().query_pairs(), vec![
+    /// assert_eq!(req.request_url()?.query_pairs(), vec![
     ///     ("foo", "42"),
     ///     ("foo", "43")
     /// ]);

src/response.rs

@@ -242,14 +242,15 @@ impl Response {
     ///
     /// ```
     /// use std::io::Read;
-    /// # fn main() -> Result<(), ureq::Error> {
+    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
     /// # ureq::is_test(true);
     /// let resp = ureq::get("http://httpbin.org/bytes/100")
     ///     .call()?;
     ///
     /// assert!(resp.has("Content-Length"));
-    /// let len = resp.header("Content-Length")
+    /// let len: usize = resp.header("Content-Length")
-    ///     .and_then(|s| s.parse::<usize>().ok()).unwrap();
+    ///     .unwrap()
+    ///     .parse()?;
     ///
     /// let mut bytes: Vec<u8> = Vec::with_capacity(len);
     /// resp.into_reader()
@@ -632,15 +633,18 @@ impl FromStr for Response {
     ///
     /// Example:
     /// ```
+    /// # fn main() -> Result<(), ureq::Error> {
     /// let s = "HTTP/1.1 200 OK\r\n\
     ///     X-Forwarded-For: 1.2.3.4\r\n\
     ///     Content-Type: text/plain\r\n\
     ///     \r\n\
     ///     Hello World!!!";
-    /// let resp = s.parse::<ureq::Response>().unwrap();
+    /// let resp: ureq::Response = s.parse()?;
     /// assert!(resp.has("X-Forwarded-For"));
-    /// let body = resp.into_string().unwrap();
+    /// let body = resp.into_string()?;
     /// assert_eq!(body, "Hello World!!!");
+    /// # Ok(())
+    /// # }
     /// ```
     fn from_str(s: &str) -> Result<Self, Self::Err> {
         let stream = Stream::from_vec(s.as_bytes().to_owned());