Skip to content

Commit

Permalink
docs: document SyntaxViolation variants, remove bare URLs (#924)
Browse files Browse the repository at this point in the history 
* doc: syntax violation variants

* fix: rustdoc::bare_urls
  • Loading branch information
@aatifsyed
aatifsyed committed Apr 12, 2024
1 parent fd042e0 commit 8b8431b
Show file tree
Hide file tree
Showing 3 changed files with 34 additions and 31 deletions.
10 changes: 5 additions & 5 deletions idna/src/uts46.rs
View file
Expand Up @@ -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);
Expand All @@ -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) {
Expand All @@ -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 {
Expand Down Expand Up @@ -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());
Expand Down
7 changes: 5 additions & 2 deletions url/src/parser.rs
View file
Expand Up @@ -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,
)+
}
Expand Down
48 changes: 24 additions & 24 deletions url/src/quirks.rs
View file
Expand Up @@ -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.
Expand Down Expand Up @@ -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)) => {
Expand All @@ -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 `:`,
Expand All @@ -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() {
Expand All @@ -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.
Expand Down Expand Up @@ -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() {
Expand Down Expand Up @@ -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;
Expand All @@ -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;
Expand All @@ -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,
Expand All @@ -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,
Expand Down

0 comments on commit 8b8431b

Please sign in to comment.