Auto merge of #382 - rap2hpoutre:master, r=SimonSapin

add more documentation for errors

More documentations for errors.  See #319 and #379

_Side question: I don't know how to document errors when a function returns `Result<(), ()>` so I did not document that part. I would be happy to see one example._

<!-- Reviewable:start -->
---
This change is [<img src="https://reviewable.io/review_button.svg" height="34" align="absmiddle" alt="Reviewable"/>](https://reviewable.io/reviews/servo/rust-url/382)
<!-- Reviewable:end -->

src/lib.rs

@@ -281,6 +281,13 @@ impl Url {
     /// # }
     /// # run().unwrap();
     /// ```
+    ///
+    /// # Errors
+    ///
+    /// If the function can not parse an absolute URL from the given string,
+    /// a [`ParseError`] variant will be returned.
+    ///
+    /// [`ParseError`]: enum.ParseError.html
     #[inline]
     pub fn parse_with_params<I, K, V>(input: &str, iter: I) -> Result<Url, ::ParseError>
         where I: IntoIterator,
@@ -321,6 +328,13 @@ impl Url {
     /// # }
     /// # run().unwrap();
     /// ```
+    ///
+    /// # Errors
+    ///
+    /// If the function can not parse an URL from the given string 
+    /// with this URL as the base URL, a [`ParseError`] variant will be returned.
+    ///
+    /// [`ParseError`]: enum.ParseError.html
     #[inline]
     pub fn join(&self, input: &str) -> Result<Url, ::ParseError> {
         Url::options().base_url(Some(self)).parse(input)
@@ -1455,9 +1469,6 @@ impl Url {
 
     /// Change this URL’s host.
     ///
-    /// If this URL is cannot-be-a-base or there is an error parsing the given `host`,
-    /// do nothing and return `Err`.
-    ///
     /// Removing the host (calling this with `None`)
     /// will also remove any username, password, and port number.
     ///
@@ -1531,6 +1542,13 @@ impl Url {
     /// # }
     /// # run().unwrap();
     /// ```
+    ///
+    /// # Errors
+    ///
+    /// If this URL is cannot-be-a-base or there is an error parsing the given `host`,
+    /// a [`ParseError`] variant will be returned.
+    ///
+    /// [`ParseError`]: enum.ParseError.html
     pub fn set_host(&mut self, host: Option<&str>) -> Result<(), ParseError> {
         if self.cannot_be_a_base() {
             return Err(ParseError::SetHostOnCannotBeABaseUrl)