Auto merge of #481 - BradyMcd:port-documentation, r=SimonSapin

Port documentation

Just a simple addition to the documentation. The fact that default port numbers are automatically elided makes perfect sense, but it caught me off and I found wasn't terribly well reflected in the documentation so I added a callout and an example on `port( )` and `set_port( )` function documentations.

<!-- 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/481)
<!-- Reviewable:end -->

src/lib.rs

@@ -918,6 +918,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
     ///
     /// ```
@@ -928,6 +931,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(())
@@ -1427,6 +1433,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`.
     ///
@@ -1449,6 +1457,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:
     ///
     /// ```