Merge remote-tracking branch 'origin/master' into 2.0

README.md

@@ -1,7 +1,7 @@
 rust-url
 ========
 
-[![Travis build Status](https://travis-ci.org/servo/rust-url.svg?branch=master)](https://travis-ci.org/servo/rust-url) [![Appveyor build status](https://ci.appveyor.com/api/projects/status/ulkqx2xcemyod6xa?svg=true)](https://ci.appveyor.com/project/Manishearth/rust-url)
+[![Travis build Status](https://travis-ci.com/servo/rust-url.svg?branch=master)](https://travis-ci.com/servo/rust-url) [![Appveyor build status](https://ci.appveyor.com/api/projects/status/ulkqx2xcemyod6xa?svg=true)](https://ci.appveyor.com/project/Manishearth/rust-url)
 
 URL library for Rust, based on the [URL Standard](https://url.spec.whatwg.org/).
 

src/lib.rs

@@ -909,6 +909,9 @@ impl Url {
 
     /// Return the port number for this URL, if any.
     ///
+    /// Note that default port numbers are never reflected by the serialization,
+    /// use the `port_or_known_default()` method if you want a default port number returned.
+    ///
     /// # Examples
     ///
     /// ```
@@ -919,6 +922,9 @@ impl Url {
     /// let url = Url::parse("https://example.com")?;
     /// assert_eq!(url.port(), None);
     ///
+    /// let url = Url::parse("https://example.com:443/")?;
+    /// assert_eq!(url.port(), None);
+    ///
     /// let url = Url::parse("ssh://example.com:22")?;
     /// assert_eq!(url.port(), Some(22));
     /// # Ok(())
@@ -1383,6 +1389,8 @@ impl Url {
 
     /// Change this URL’s port number.
     ///
+    /// Note that default port numbers are not reflected in the serialization.
+    ///
     /// If this URL is cannot-be-a-base, does not have a host, or has the `file` scheme;
     /// do nothing and return `Err`.
     ///
@@ -1405,6 +1413,22 @@ impl Url {
     /// # run().unwrap();
     /// ```
     ///
+    /// Known default port numbers are not reflected:
+    ///
+    /// ```rust
+    /// use url::Url;
+    /// # use std::error::Error;
+    ///
+    /// # fn run() -> Result<(), Box<Error>> {
+    /// let mut url = Url::parse("https://example.org/")?;
+    ///
+    /// url.set_port(Some(443)).map_err(|_| "cannot be base")?;
+    /// assert!(url.port().is_none());
+    /// # Ok(())
+    /// # }
+    /// # run().unwrap();
+    /// ```
+    ///
     /// Cannot set port for cannot-be-a-base URLs:
     ///
     /// ```