Improve doctests with less unwraps

- Add `CannotBeBaseError` struct to examples involving cannot-be-a-base URLs, map unit errors to this type;
- Replace previous `path_segment().expect()` with `CannotBeBaseError` mapping;
- replace try! with ? in url.with_defaul_port example.

src/lib.rs

@@ -870,9 +870,8 @@ impl Url {
     /// # use url::Url;
     /// # use std::net::TcpStream;
     /// # use std::io;
-    ///
     /// fn connect(url: &Url) -> io::Result<TcpStream> {
-    ///     TcpStream::connect(try!(url.with_default_port(default_port)))
+    ///     TcpStream::connect(url.with_default_port(default_port)?)
     /// }
     ///
     /// fn default_port(url: &Url) -> Result<u16, ()> {
@@ -925,17 +924,29 @@ impl Url {
     ///
     /// ```
     /// use url::Url;
-    /// # use url::ParseError;
+    /// use std::error::Error;
+    /// use std::fmt;
+    ///
+    /// #[derive(Debug)]
+    /// struct CannotBeBaseError;
+    /// impl fmt::Display for CannotBeBaseError {
+    ///     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+    ///         f.write_str(self.description())
+    ///     }
+    /// }
+    /// impl Error for CannotBeBaseError {
+    ///     fn description(&self) -> &str { "cannot be a base" }
+    /// }
     ///
-    /// # fn run() -> Result<(), ParseError> {
+    /// # fn run() -> Result<(), Box<Error>> {
     /// let url = Url::parse("https://example.com/foo/bar")?;
-    /// let mut path_segments = url.path_segments().expect("not a cannot-be-a-base URL");
+    /// let mut path_segments = url.path_segments().ok_or_else(|| CannotBeBaseError)?;
     /// assert_eq!(path_segments.next(), Some("foo"));
     /// assert_eq!(path_segments.next(), Some("bar"));
     /// assert_eq!(path_segments.next(), None);
     ///
     /// let url = Url::parse("https://example.com")?;
-    /// let mut path_segments = url.path_segments().expect("not a cannot-be-a-base URL");
+    /// let mut path_segments = url.path_segments().ok_or_else(|| CannotBeBaseError)?;
     /// assert_eq!(path_segments.next(), Some(""));
     /// assert_eq!(path_segments.next(), None);
     ///
@@ -1160,15 +1171,27 @@ impl Url {
     ///
     /// ```
     /// use url::Url;
-    /// # use url::ParseError;
+    /// use std::error::Error;
+    /// use std::fmt;
+    ///
+    /// #[derive(Debug)]
+    /// struct CannotBeBaseError;
+    /// impl fmt::Display for CannotBeBaseError {
+    ///     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+    ///         f.write_str(self.description())
+    ///     }
+    /// }
+    /// impl Error for CannotBeBaseError {
+    ///     fn description(&self) -> &str { "cannot be a base" }
+    /// }
     ///
-    /// # fn run() -> Result<(), ParseError> {
+    /// # fn run() -> Result<(), Box<Error>> {
     /// let mut url = Url::parse("ssh://example.net:2048/")?;
     ///
-    /// url.set_port(Some(4096)).expect("not a cannot-be-a-base URL");
+    /// url.set_port(Some(4096)).map_err(|_| CannotBeBaseError)?;
     /// assert_eq!(url.as_str(), "ssh://example.net:4096/");
     ///
-    /// url.set_port(None).expect("not a cannot-be-a-base URL");
+    /// url.set_port(None).map_err(|_| CannotBeBaseError)?;
     /// assert_eq!(url.as_str(), "ssh://example.net/");
     /// # Ok(())
     /// # }

src/path_segments.rs

@@ -18,14 +18,28 @@ use Url;
 /// Examples:
 ///
 /// ```rust
-/// # use url::{Url, ParseError};
+/// use url::Url;
+/// use std::error::Error;
+/// use std::fmt;
 ///
-/// # fn run() -> Result<(), ParseError> {
+/// #[derive(Debug)]
+/// struct CannotBeBaseError;
+/// impl fmt::Display for CannotBeBaseError {
+///     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+///         f.write_str(self.description())
+///     }
+/// }
+/// impl Error for CannotBeBaseError {
+///     fn description(&self) -> &str { "cannot be a base" }
+/// }
+///
+/// # fn run() -> Result<(), Box<Error>> {
 /// let mut url = Url::parse("mailto:me@example.com")?;
 /// assert!(url.path_segments_mut().is_err());
 ///
 /// let mut url = Url::parse("http://example.net/foo/index.html")?;
-/// url.path_segments_mut().unwrap().pop().push("img").push("2/100%.png");
+/// url.path_segments_mut().map_err(|_| CannotBeBaseError)?
+///     .pop().push("img").push("2/100%.png");
 /// assert_eq!(url.as_str(), "http://example.net/foo/img/2%2F100%25.png");
 /// # Ok(())
 /// # }
@@ -64,11 +78,25 @@ impl<'a> PathSegmentsMut<'a> {
     /// Example:
     ///
     /// ```rust
-    /// # use url::{Url, ParseError};
-    /// 
-    /// # fn run() -> Result<(), ParseError> {
+    /// use url::Url;
+    /// use std::error::Error;
+    /// use std::fmt;
+    ///
+    /// #[derive(Debug)]
+    /// struct CannotBeBaseError;
+    /// impl fmt::Display for CannotBeBaseError {
+    ///     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+    ///         f.write_str(self.description())
+    ///     }
+    /// }
+    /// impl Error for CannotBeBaseError {
+    ///     fn description(&self) -> &str { "cannot be a base" }
+    /// }
+    ///
+    /// # fn run() -> Result<(), Box<Error>> {
     /// let mut url = Url::parse("https://github.com/servo/rust-url/")?;
-    /// url.path_segments_mut().unwrap().clear().push("logout");
+    /// url.path_segments_mut().map_err(|_| CannotBeBaseError)?
+    ///     .clear().push("logout");
     /// assert_eq!(url.as_str(), "https://github.com/logout");
     /// # Ok(())
     /// # }
@@ -90,14 +118,29 @@ impl<'a> PathSegmentsMut<'a> {
     ///
     /// ```rust
     /// # use url::{Url, ParseError};
-    /// 
-    /// # fn run() -> Result<(), ParseError> {
+    /// use std::error::Error;
+    /// use std::fmt;
+    ///
+    /// #[derive(Debug)]
+    /// struct CannotBeBaseError;
+    /// impl fmt::Display for CannotBeBaseError {
+    ///     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+    ///         f.write_str(self.description())
+    ///     }
+    /// }
+    /// impl Error for CannotBeBaseError {
+    ///     fn description(&self) -> &str { "cannot be a base" }
+    /// }
+    ///
+    /// # fn run() -> Result<(), Box<Error>> {
     /// let mut url = Url::parse("https://github.com/servo/rust-url/")?;
-    /// url.path_segments_mut().unwrap().push("pulls");
+    /// url.path_segments_mut().map_err(|_| CannotBeBaseError)?
+    ///     .push("pulls");
     /// assert_eq!(url.as_str(), "https://github.com/servo/rust-url//pulls");
     ///
     /// let mut url = Url::parse("https://github.com/servo/rust-url/")?;
-    /// url.path_segments_mut().unwrap().pop_if_empty().push("pulls");
+    /// url.path_segments_mut().map_err(|_| CannotBeBaseError)?
+    ///     .pop_if_empty().push("pulls");
     /// assert_eq!(url.as_str(), "https://github.com/servo/rust-url/pulls");
     /// # Ok(())
     /// # }
@@ -150,14 +193,28 @@ impl<'a> PathSegmentsMut<'a> {
     /// Example:
     ///
     /// ```rust
-    /// # use url::{Url, ParseError};
-    /// 
-    /// # fn run() -> Result<(), ParseError> {
+    /// use url::Url;
+    /// use std::error::Error;
+    /// use std::fmt;
+    ///
+    /// #[derive(Debug)]
+    /// struct CannotBeBaseError;
+    /// impl fmt::Display for CannotBeBaseError {
+    ///     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+    ///         f.write_str(self.description())
+    ///     }
+    /// }
+    /// impl Error for CannotBeBaseError {
+    ///     fn description(&self) -> &str { "cannot be a base" }
+    /// }
+    ///
+    /// # fn run() -> Result<(), Box<Error>> {
     /// let mut url = Url::parse("https://github.com/")?;
     /// let org = "servo";
     /// let repo = "rust-url";
     /// let issue_number = "188";
-    /// url.path_segments_mut().unwrap().extend(&[org, repo, "issues", issue_number]);
+    /// url.path_segments_mut().map_err(|_| CannotBeBaseError)?
+    ///     .extend(&[org, repo, "issues", issue_number]);
     /// assert_eq!(url.as_str(), "https://github.com/servo/rust-url/issues/188");
     /// # Ok(())
     /// # }
@@ -167,11 +224,25 @@ impl<'a> PathSegmentsMut<'a> {
     /// a segment is ignored if it is `"."` or `".."`:
     ///
     /// ```rust
-    /// # use url::{Url, ParseError};
-    /// 
-    /// # fn run() -> Result<(), ParseError> {
+    /// use url::Url;
+    /// use std::error::Error;
+    /// use std::fmt;
+    ///
+    /// #[derive(Debug)]
+    /// struct CannotBeBaseError;
+    /// impl fmt::Display for CannotBeBaseError {
+    ///     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+    ///         f.write_str(self.description())
+    ///     }
+    /// }
+    /// impl Error for CannotBeBaseError {
+    ///     fn description(&self) -> &str { "cannot be a base" }
+    /// }
+    ///
+    /// # fn run() -> Result<(), Box<Error>> {
     /// let mut url = Url::parse("https://github.com/servo")?;
-    /// url.path_segments_mut().unwrap().extend(&["..", "rust-url", ".", "pulls"]);
+    /// url.path_segments_mut().map_err(|_| CannotBeBaseError)?
+    ///     .extend(&["..", "rust-url", ".", "pulls"]);
     /// assert_eq!(url.as_str(), "https://github.com/servo/rust-url/pulls");
     /// # Ok(())
     /// # }