From 8b8431bbe10d0f06c53885d5ba2602d69f61888f Mon Sep 17 00:00:00 2001 From: Aatif Syed <38045910+aatifsyed@users.noreply.github.com> Date: Fri, 12 Apr 2024 11:49:09 +0100 Subject: [PATCH] docs: document SyntaxViolation variants, remove bare URLs (#924) * doc: syntax violation variants * fix: rustdoc::bare_urls --- idna/src/uts46.rs | 10 +++++----- url/src/parser.rs | 7 +++++-- url/src/quirks.rs | 48 +++++++++++++++++++++++------------------------ 3 files changed, 34 insertions(+), 31 deletions(-) diff --git a/idna/src/uts46.rs b/idna/src/uts46.rs index b082416c8..d52a4d0fb 100644 --- a/idna/src/uts46.rs +++ b/idna/src/uts46.rs @@ -475,7 +475,7 @@ impl Idna { errors } - /// 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 + /// #[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 impl Default for Config { fn default() -> Self { Config { @@ -566,14 +566,14 @@ impl Config { self } - /// http://www.unicode.org/reports/tr46/#ToASCII + /// pub fn to_ascii(self, domain: &str) -> Result { 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 + /// pub fn to_unicode(self, domain: &str) -> (String, Result<(), Errors>) { let mut codec = Idna::new(self); let mut out = String::with_capacity(domain.len()); diff --git a/url/src/parser.rs b/url/src/parser.rs index 7d94d1d71..2e3a4f644 100644 --- a/url/src/parser.rs +++ b/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, )+ } diff --git a/url/src/quirks.rs b/url/src/quirks.rs index 1f4600c46..391a50dbe 100644 --- a/url/src/quirks.rs +++ b/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 //! //! Unless you need to be interoperable with web browsers, //! you probably want to use `Url` method instead. @@ -57,7 +57,7 @@ pub fn internal_components(url: &Url) -> InternalComponents { } } -/// 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, @@ -65,7 +65,7 @@ pub fn domain_to_ascii(domain: &str) -> String { } } -/// 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 pub fn href(url: &Url) -> &str { url.as_str() } -/// Setter for https://url.spec.whatwg.org/#dom-url-href +/// Setter for 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 pub fn origin(url: &Url) -> String { url.origin().ascii_serialization() } -/// Getter for https://url.spec.whatwg.org/#dom-url-protocol +/// Getter for #[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 #[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 #[inline] pub fn username(url: &Url) -> &str { url.username() } -/// Setter for https://url.spec.whatwg.org/#dom-url-username +/// Setter for #[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 #[inline] pub fn password(url: &Url) -> &str { url.password().unwrap_or("") } -/// Setter for https://url.spec.whatwg.org/#dom-url-password +/// Setter for #[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 #[inline] pub fn host(url: &Url) -> &str { &url[Position::BeforeHost..Position::AfterPort] } -/// Setter for https://url.spec.whatwg.org/#dom-url-host +/// Setter for #[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 #[inline] pub fn hostname(url: &Url) -> &str { url.host_str().unwrap_or("") } -/// Setter for https://url.spec.whatwg.org/#dom-url-hostname +/// Setter for #[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 #[inline] pub fn port(url: &Url) -> &str { &url[Position::BeforePort..Position::AfterPort] } -/// Setter for https://url.spec.whatwg.org/#dom-url-port +/// Setter for #[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 #[inline] pub fn pathname(url: &Url) -> &str { url.path() } -/// Setter for https://url.spec.whatwg.org/#dom-url-pathname +/// Setter for 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 pub fn search(url: &Url) -> &str { trim(&url[Position::AfterPath..Position::AfterQuery]) } -/// Setter for https://url.spec.whatwg.org/#dom-url-search +/// Setter for 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 pub fn hash(url: &Url) -> &str { trim(&url[Position::AfterQuery..]) } -/// Setter for https://url.spec.whatwg.org/#dom-url-hash +/// Setter for pub fn set_hash(url: &mut Url, new_hash: &str) { url.set_fragment(match new_hash { // If the given value is the empty string,