docs: document SyntaxViolation variants, remove bare URLs (servo#924)

* doc: syntax violation variants

* fix: rustdoc::bare_urls

Author: aatifsyed

idna/src/uts46.rs

@@ -475,7 +475,7 @@ impl Idna {
         errors
     }
 
-    /// http://www.unicode.org/reports/tr46/#ToASCII
+    /// <http://www.unicode.org/reports/tr46/#ToASCII>
     #[allow(clippy::wrong_self_convention)]
     pub fn to_ascii(&mut self, domain: &str, out: &mut String) -> Result<(), Errors> {
         let mut errors = self.to_ascii_inner(domain, out);
@@ -497,7 +497,7 @@ impl Idna {
         errors.into()
     }
 
-    /// http://www.unicode.org/reports/tr46/#ToUnicode
+    /// <http://www.unicode.org/reports/tr46/#ToUnicode>
     #[allow(clippy::wrong_self_convention)]
     pub fn to_unicode(&mut self, domain: &str, out: &mut String) -> Result<(), Errors> {
         if is_simple(domain) {
@@ -518,7 +518,7 @@ pub struct Config {
     use_idna_2008_rules: bool,
 }
 
-/// The defaults are that of https://url.spec.whatwg.org/#idna
+/// The defaults are that of <https://url.spec.whatwg.org/#idna>
 impl Default for Config {
     fn default() -> Self {
         Config {
@@ -566,14 +566,14 @@ impl Config {
         self
     }
 
-    /// http://www.unicode.org/reports/tr46/#ToASCII
+    /// <http://www.unicode.org/reports/tr46/#ToASCII>
     pub fn to_ascii(self, domain: &str) -> Result<String, Errors> {
         let mut result = String::with_capacity(domain.len());
         let mut codec = Idna::new(self);
         codec.to_ascii(domain, &mut result).map(|()| result)
     }
 
-    /// http://www.unicode.org/reports/tr46/#ToUnicode
+    /// <http://www.unicode.org/reports/tr46/#ToUnicode>
     pub fn to_unicode(self, domain: &str) -> (String, Result<(), Errors>) {
         let mut codec = Idna::new(self);
         let mut out = String::with_capacity(domain.len());

url/src/parser.rs

@@ -94,15 +94,18 @@ impl From<::idna::Errors> for ParseError {
 }
 
 macro_rules! syntax_violation_enum {
-    ($($name: ident => $description: expr,)+) => {
+    ($($name: ident => $description: literal,)+) => {
         /// Non-fatal syntax violations that can occur during parsing.
         ///
         /// This may be extended in the future so exhaustive matching is
-        /// discouraged with an unused variant.
+        /// forbidden.
         #[derive(PartialEq, Eq, Clone, Copy, Debug)]
         #[non_exhaustive]
         pub enum SyntaxViolation {
             $(
+                /// ```text
+                #[doc = $description]
+                /// ```
                 $name,
             )+
         }

url/src/quirks.rs

@@ -6,7 +6,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Getters and setters for URL components implemented per https://url.spec.whatwg.org/#api
+//! Getters and setters for URL components implemented per <https://url.spec.whatwg.org/#api>
 //!
 //! Unless you need to be interoperable with web browsers,
 //! you probably want to use `Url` method instead.
@@ -57,15 +57,15 @@ pub fn internal_components(url: &Url) -> InternalComponents {
     }
 }
 
-/// https://url.spec.whatwg.org/#dom-url-domaintoascii
+/// <https://url.spec.whatwg.org/#dom-url-domaintoascii>
 pub fn domain_to_ascii(domain: &str) -> String {
     match Host::parse(domain) {
         Ok(Host::Domain(domain)) => domain,
         _ => String::new(),
     }
 }
 
-/// https://url.spec.whatwg.org/#dom-url-domaintounicode
+/// <https://url.spec.whatwg.org/#dom-url-domaintounicode>
 pub fn domain_to_unicode(domain: &str) -> String {
     match Host::parse(domain) {
         Ok(Host::Domain(ref domain)) => {
@@ -76,29 +76,29 @@ pub fn domain_to_unicode(domain: &str) -> String {
     }
 }
 
-/// Getter for https://url.spec.whatwg.org/#dom-url-href
+/// Getter for <https://url.spec.whatwg.org/#dom-url-href>
 pub fn href(url: &Url) -> &str {
     url.as_str()
 }
 
-/// Setter for https://url.spec.whatwg.org/#dom-url-href
+/// Setter for <https://url.spec.whatwg.org/#dom-url-href>
 pub fn set_href(url: &mut Url, value: &str) -> Result<(), ParseError> {
     *url = Url::parse(value)?;
     Ok(())
 }
 
-/// Getter for https://url.spec.whatwg.org/#dom-url-origin
+/// Getter for <https://url.spec.whatwg.org/#dom-url-origin>
 pub fn origin(url: &Url) -> String {
     url.origin().ascii_serialization()
 }
 
-/// Getter for https://url.spec.whatwg.org/#dom-url-protocol
+/// Getter for <https://url.spec.whatwg.org/#dom-url-protocol>
 #[inline]
 pub fn protocol(url: &Url) -> &str {
     &url.as_str()[..url.scheme().len() + ":".len()]
 }
 
-/// Setter for https://url.spec.whatwg.org/#dom-url-protocol
+/// Setter for <https://url.spec.whatwg.org/#dom-url-protocol>
 #[allow(clippy::result_unit_err)]
 pub fn set_protocol(url: &mut Url, mut new_protocol: &str) -> Result<(), ()> {
     // The scheme state in the spec ignores everything after the first `:`,
@@ -109,25 +109,25 @@ pub fn set_protocol(url: &mut Url, mut new_protocol: &str) -> Result<(), ()> {
     url.set_scheme(new_protocol)
 }
 
-/// Getter for https://url.spec.whatwg.org/#dom-url-username
+/// Getter for <https://url.spec.whatwg.org/#dom-url-username>
 #[inline]
 pub fn username(url: &Url) -> &str {
     url.username()
 }
 
-/// Setter for https://url.spec.whatwg.org/#dom-url-username
+/// Setter for <https://url.spec.whatwg.org/#dom-url-username>
 #[allow(clippy::result_unit_err)]
 pub fn set_username(url: &mut Url, new_username: &str) -> Result<(), ()> {
     url.set_username(new_username)
 }
 
-/// Getter for https://url.spec.whatwg.org/#dom-url-password
+/// Getter for <https://url.spec.whatwg.org/#dom-url-password>
 #[inline]
 pub fn password(url: &Url) -> &str {
     url.password().unwrap_or("")
 }
 
-/// Setter for https://url.spec.whatwg.org/#dom-url-password
+/// Setter for <https://url.spec.whatwg.org/#dom-url-password>
 #[allow(clippy::result_unit_err)]
 pub fn set_password(url: &mut Url, new_password: &str) -> Result<(), ()> {
     url.set_password(if new_password.is_empty() {
@@ -137,13 +137,13 @@ pub fn set_password(url: &mut Url, new_password: &str) -> Result<(), ()> {
     })
 }
 
-/// Getter for https://url.spec.whatwg.org/#dom-url-host
+/// Getter for <https://url.spec.whatwg.org/#dom-url-host>
 #[inline]
 pub fn host(url: &Url) -> &str {
     &url[Position::BeforeHost..Position::AfterPort]
 }
 
-/// Setter for https://url.spec.whatwg.org/#dom-url-host
+/// Setter for <https://url.spec.whatwg.org/#dom-url-host>
 #[allow(clippy::result_unit_err)]
 pub fn set_host(url: &mut Url, new_host: &str) -> Result<(), ()> {
     // If context object’s url’s cannot-be-a-base-URL flag is set, then return.
@@ -190,13 +190,13 @@ pub fn set_host(url: &mut Url, new_host: &str) -> Result<(), ()> {
     Ok(())
 }
 
-/// Getter for https://url.spec.whatwg.org/#dom-url-hostname
+/// Getter for <https://url.spec.whatwg.org/#dom-url-hostname>
 #[inline]
 pub fn hostname(url: &Url) -> &str {
     url.host_str().unwrap_or("")
 }
 
-/// Setter for https://url.spec.whatwg.org/#dom-url-hostname
+/// Setter for <https://url.spec.whatwg.org/#dom-url-hostname>
 #[allow(clippy::result_unit_err)]
 pub fn set_hostname(url: &mut Url, new_hostname: &str) -> Result<(), ()> {
     if url.cannot_be_a_base() {
@@ -232,13 +232,13 @@ pub fn set_hostname(url: &mut Url, new_hostname: &str) -> Result<(), ()> {
     }
 }
 
-/// Getter for https://url.spec.whatwg.org/#dom-url-port
+/// Getter for <https://url.spec.whatwg.org/#dom-url-port>
 #[inline]
 pub fn port(url: &Url) -> &str {
     &url[Position::BeforePort..Position::AfterPort]
 }
 
-/// Setter for https://url.spec.whatwg.org/#dom-url-port
+/// Setter for <https://url.spec.whatwg.org/#dom-url-port>
 #[allow(clippy::result_unit_err)]
 pub fn set_port(url: &mut Url, new_port: &str) -> Result<(), ()> {
     let result;
@@ -262,13 +262,13 @@ pub fn set_port(url: &mut Url, new_port: &str) -> Result<(), ()> {
     }
 }
 
-/// Getter for https://url.spec.whatwg.org/#dom-url-pathname
+/// Getter for <https://url.spec.whatwg.org/#dom-url-pathname>
 #[inline]
 pub fn pathname(url: &Url) -> &str {
     url.path()
 }
 
-/// Setter for https://url.spec.whatwg.org/#dom-url-pathname
+/// Setter for <https://url.spec.whatwg.org/#dom-url-pathname>
 pub fn set_pathname(url: &mut Url, new_pathname: &str) {
     if url.cannot_be_a_base() {
         return;
@@ -291,12 +291,12 @@ pub fn set_pathname(url: &mut Url, new_pathname: &str) {
     }
 }
 
-/// Getter for https://url.spec.whatwg.org/#dom-url-search
+/// Getter for <https://url.spec.whatwg.org/#dom-url-search>
 pub fn search(url: &Url) -> &str {
     trim(&url[Position::AfterPath..Position::AfterQuery])
 }
 
-/// Setter for https://url.spec.whatwg.org/#dom-url-search
+/// Setter for <https://url.spec.whatwg.org/#dom-url-search>
 pub fn set_search(url: &mut Url, new_search: &str) {
     url.set_query(match new_search {
         "" => None,
@@ -305,12 +305,12 @@ pub fn set_search(url: &mut Url, new_search: &str) {
     })
 }
 
-/// Getter for https://url.spec.whatwg.org/#dom-url-hash
+/// Getter for <https://url.spec.whatwg.org/#dom-url-hash>
 pub fn hash(url: &Url) -> &str {
     trim(&url[Position::AfterQuery..])
 }
 
-/// Setter for https://url.spec.whatwg.org/#dom-url-hash
+/// Setter for <https://url.spec.whatwg.org/#dom-url-hash>
 pub fn set_hash(url: &mut Url, new_hash: &str) {
     url.set_fragment(match new_hash {
         // If the given value is the empty string,