Deprecate the url crate.

The replacement is [rust-url](https://github.com/servo/rust-url),
which can be used with Cargo.

Fix #15874
Fix #10707
Close #10706
Close #10705
Close #8486

Author: SimonSapin

src/liburl/lib.rs

@@ -11,7 +11,7 @@
 //! Types/fns concerning URLs (see RFC 3986)
 
 #![crate_name = "url"]
-#![experimental]
+#![deprecated="This is being removed. Use rust-url instead. http://servo.github.io/rust-url/"]
 #![crate_type = "rlib"]
 #![crate_type = "dylib"]
 #![license = "MIT/ASL2"]
@@ -35,6 +35,7 @@ use std::path::BytesContainer;
 /// # Example
 ///
 /// ```rust
+/// # #![allow(deprecated)]
 /// use url::Url;
 ///
 /// let raw = "https://username@example.com:8080/foo/bar?baz=qux#quz";
@@ -214,6 +215,7 @@ fn encode_inner<T: BytesContainer>(c: T, full_url: bool) -> String {
 /// # Example
 ///
 /// ```rust
+/// # #![allow(deprecated)]
 /// use url::encode;
 ///
 /// let url = encode("https://example.com/Rust (programming language)");
@@ -241,6 +243,7 @@ pub type DecodeResult<T> = Result<T, String>;
 /// # Example
 ///
 /// ```rust
+/// # #![allow(deprecated)]
 /// use url::decode;
 ///
 /// let url = decode("https://example.com/Rust%20(programming%20language)");
@@ -428,6 +431,7 @@ fn query_from_str(rawquery: &str) -> DecodeResult<Query> {
 /// # Example
 ///
 /// ```rust
+/// # #![allow(deprecated)]
 /// let query = vec![("title".to_string(), "The Village".to_string()),
 ///                  ("north".to_string(), "52.91".to_string()),
 ///                  ("west".to_string(), "4.10".to_string())];
@@ -453,6 +457,7 @@ pub fn query_to_str(query: &Query) -> String {
 /// # Example
 ///
 /// ```rust
+/// # #![allow(deprecated)]
 /// use url::get_scheme;
 ///
 /// let scheme = match get_scheme("https://example.com/") {

src/test/compile-fail/deprecated-url.rs

@@ -0,0 +1,20 @@
+// Copyright 2014 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+// ignore-tidy-linelength
+
+#![deny(deprecated)]
+
+extern crate url;
+
+fn main() {
+    let _ = url::Url::parse("http://example.com");
+    //~^ ERROR use of deprecated item: This is being removed. Use rust-url instead. http://servo.github.io/rust-url/
+}