Auto merge of #344 - tmccombs:doc-origin, r=SimonSapin

Doc origin

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

Author: bors-servo

src/lib.rs

@@ -1368,6 +1368,7 @@ impl Url {
     /// Change this URL’s scheme.
     ///
     /// Do nothing and return `Err` if:
+    ///
     /// * The new scheme is not in `[a-zA-Z][a-zA-Z0-9+.-]+`
     /// * This URL is cannot-be-a-base and the new scheme is one of
     ///   `http`, `https`, `ws`, `wss`, `ftp`, or `gopher`

src/origin.rs

@@ -34,6 +34,22 @@ pub fn url_origin(url: &Url) -> Origin {
 }
 
 /// The origin of an URL
+///
+/// Two URLs with the same origin are considered
+/// to originate from the same entity and can therefore trust
+/// each other.
+///
+/// The origin is determined based on the scheme as follows:
+///
+/// - If the scheme is "blob" the origin is the origin of the
+///   URL contained in the path component. If parsing fails,
+///   it is an opaque origin.
+/// - If the scheme is "ftp", "gopher", "http", "https", "ws", or "wss",
+///   then the origin is a tuple of the scheme, host, and port.
+/// - If the scheme is anything else, the origin is opaque, meaning
+///   the URL does not have the same origin as any other URL.
+///
+/// For more information see https://url.spec.whatwg.org/#origin
 #[derive(PartialEq, Eq, Clone, Debug)]
 pub enum Origin {
     /// A globally unique identifier