Update doc

README.md

@@ -35,8 +35,10 @@ A full-featured URI handling library compliant with [RFC 3986]. It is:
     You can build a `Uri<String>` using the builder pattern:
 
     ```rust
+    const SCHEME_FOO: &Scheme = Scheme::new_or_panic("foo");
+
     let uri: Uri<String> = Uri::builder()
-        .scheme(Scheme::new_or_panic("foo"))
+        .scheme(SCHEME_FOO)
         .authority(|b| {
             b.userinfo(EStr::new_or_panic("user"))
                 .host(EStr::new_or_panic("example.com"))
@@ -45,7 +47,8 @@ A full-featured URI handling library compliant with [RFC 3986]. It is:
         .path(EStr::new_or_panic("/over/there"))
         .query(EStr::new_or_panic("name=ferret"))
         .fragment(EStr::new_or_panic("nose"))
-        .build();
+        .build()
+        .unwrap();
 
     assert_eq!(
         uri.as_str(),
@@ -58,9 +61,9 @@ A full-featured URI handling library compliant with [RFC 3986]. It is:
     ```rust
     let base = Uri::parse("http://example.com/foo/bar")?;
 
-    assert_eq!(Uri::parse("baz")?.resolve(&base)?, "http://example.com/foo/baz");
-    assert_eq!(Uri::parse("../baz")?.resolve(&base)?, "http://example.com/baz");
-    assert_eq!(Uri::parse("?baz")?.resolve(&base)?, "http://example.com/foo/bar?baz");
+    assert_eq!(Uri::parse("baz")?.resolve_against(&base)?, "http://example.com/foo/baz");
+    assert_eq!(Uri::parse("../baz")?.resolve_against(&base)?, "http://example.com/baz");
+    assert_eq!(Uri::parse("?baz")?.resolve_against(&base)?, "http://example.com/foo/bar?baz");
     ```
 
     You can normalize a URI reference:

src/builder/mod.rs

@@ -27,8 +27,10 @@ use state::*;
 /// ```
 /// use fluent_uri::{component::Scheme, encoding::EStr, Uri};
 ///
+/// const SCHEME_FOO: &Scheme = Scheme::new_or_panic("foo");
+///
 /// let uri: Uri<String> = Uri::builder()
-///     .scheme(Scheme::new_or_panic("foo"))
+///     .scheme(SCHEME_FOO)
 ///     .authority(|b| {
 ///         b.userinfo(EStr::new_or_panic("user"))
 ///             .host(EStr::new_or_panic("example.com"))
@@ -46,8 +48,8 @@ use state::*;
 /// );
 /// ```
 ///
-/// Note that [`EStr::new_or_panic`] *panics* on invalid input and should only be used
-/// when you know that the string is properly percent-encoded.
+/// Note that [`EStr::new_or_panic`] *panics* on invalid input and
+/// should normally be used with constant strings.
 /// If you want to build a percent-encoded string from scratch,
 /// use [`EString`] instead.
 ///
@@ -261,8 +263,8 @@ impl<S> Builder<S> {
 impl<S: To<SchemeEnd>> Builder<S> {
     /// Sets the [scheme] component.
     ///
-    /// Note that the scheme component is **case-insensitive** and normalized to
-    /// lowercase. You should use only lowercase in scheme names for consistency.
+    /// Note that the scheme component is *case-insensitive* and normalized to
+    /// *lowercase*. You should use only lowercase in scheme names for consistency.
     ///
     /// [scheme]: https://datatracker.ietf.org/doc/html/rfc3986/#section-3.1
     pub fn scheme(mut self, scheme: &Scheme) -> Builder<SchemeEnd> {
@@ -303,20 +305,24 @@ impl<S: To<HostEnd>> Builder<S> {
     ///
     /// - [`Ipv4Addr`] and [`IpAddr::V4`] into [`Host::Ipv4`];
     /// - [`Ipv6Addr`] and [`IpAddr::V6`] into [`Host::Ipv6`];
-    /// - `&EStr<RegName>` and `&EString<RegName>` into [`Host::RegName`].
+    /// - <code>&amp;[EStr]&lt;[RegName]&gt;</code> and
+    ///   <code>&amp;[EString]&lt;[RegName]&gt;</code>
+    ///   into [`Host::RegName`].
     ///
     /// If the contents of an input [`Host::RegName`] variant matches the
     /// `IPv4address` ABNF rule defined in [Section 3.2.2 of RFC 3986][host],
     /// the resulting [`Uri`] will output a [`Host::Ipv4`] variant instead.
     ///
-    /// Note that the host subcomponent is **case-insensitive** and normalized to
-    /// lowercase. You should use only lowercase in registered names for consistency.
+    /// Note that the host subcomponent is *case-insensitive* and normalized to
+    /// *lowercase*. You should use only lowercase in registered names for consistency.
     ///
     /// [host]: https://datatracker.ietf.org/doc/html/rfc3986/#section-3.2.2
     /// [`Ipv4Addr`]: std::net::Ipv4Addr
     /// [`IpAddr::V4`]: std::net::IpAddr::V4
     /// [`Ipv6Addr`]: std::net::Ipv6Addr
     /// [`IpAddr::V6`]: std::net::IpAddr::V6
+    /// [RegName]: crate::encoding::encoder::RegName
+    /// [EString]: crate::encoding::EString
     ///
     /// # Examples
     ///
@@ -354,11 +360,11 @@ impl AsPort for &EStr<Port> {
 }
 
 impl<S: To<PortEnd>> Builder<S> {
-    /// Sets the [port] subcomponent of authority.
+    /// Sets the [port][port-spec] subcomponent of authority.
     ///
-    /// This method takes either a `u16` or `&EStr<Port>` as argument.
+    /// This method takes either a `u16` or <code>&amp;[EStr]&lt;[Port]&gt;</code> as argument.
     ///
-    /// [port]: https://datatracker.ietf.org/doc/html/rfc3986/#section-3.2.3
+    /// [port-spec]: https://datatracker.ietf.org/doc/html/rfc3986/#section-3.2.3
     pub fn port<P: AsPort>(mut self, port: P) -> Builder<PortEnd> {
         port.push_to(&mut self.inner.buf);
         self.cast()

src/component.rs

@@ -35,11 +35,13 @@ use std::{
 /// ```
 /// use fluent_uri::{component::Scheme, Uri};
 ///
+/// const SCHEME_HTTP: &Scheme = Scheme::new_or_panic("http");
+///
 /// let uri = Uri::parse("HTTP://EXAMPLE.COM/")?;
 /// let scheme = uri.scheme().unwrap();
 ///
 /// // Case-insensitive comparison.
-/// assert_eq!(scheme, Scheme::new_or_panic("http"));
+/// assert_eq!(scheme, SCHEME_HTTP);
 /// // Case-sensitive comparison.
 /// assert_eq!(scheme.as_str(), "HTTP");
 /// # Ok::<_, fluent_uri::error::ParseError>(())
@@ -203,7 +205,7 @@ impl<'i, 'o, T: BorrowOrShare<'i, 'o, str>> Authority<T> {
     ///
     /// The square brackets enclosing an IPv6 or IPvFuture address are included.
     ///
-    /// Note that the host subcomponent is **case-insensitive**.
+    /// Note that the host subcomponent is *case-insensitive*.
     ///
     /// [host]: https://datatracker.ietf.org/doc/html/rfc3986/#section-3.2.2
     ///
@@ -233,7 +235,7 @@ impl<'i, 'o, T: BorrowOrShare<'i, 'o, str>> Authority<T> {
 
     /// Returns the parsed [host] subcomponent.
     ///
-    /// Note that the host subcomponent is **case-insensitive**.
+    /// Note that the host subcomponent is *case-insensitive*.
     ///
     /// [host]: https://datatracker.ietf.org/doc/html/rfc3986/#section-3.2.2
     ///
@@ -417,7 +419,7 @@ pub enum Host<'a> {
     IpvFuture,
     /// A registered name.
     ///
-    /// Note that registered names are **case-insensitive**.
+    /// Note that registered names are *case-insensitive*.
     RegName(&'a EStr<RegName>),
 }
 

src/lib.rs

@@ -42,10 +42,10 @@
 //! # Crate features
 //!
 //! - `net` (default): Enables [`std::net`] support.
-//!   Includes IP address fields in [`Host`] and [`Authority::to_socket_addrs`].
-//!   Disabling this will not affect the behavior of [`Uri::parse`].
+//!   Required for IP address fields in [`Host`] and [`Authority::to_socket_addrs`].
+//!   Disabling `net` will not affect the behavior of [`Uri::parse`].
 //!
-//! - `std` (default): Enables [`std`] support. Includes [`Error`] implementations
+//! - `std` (default): Enables [`std`] support. Required for [`Error`] implementations
 //!   and [`Authority::to_socket_addrs`]. Disabling `std` while enabling `net`
 //!   requires [`core::net`] and a minimum Rust version of `1.77`.
 //!
@@ -189,7 +189,7 @@ impl<T> Uri<T> {
     /// the [`URI-reference`] ABNF rule from RFC 3986.
     ///
     /// From a [`ParseError<String>`], you may recover or strip the input
-    /// by calling [`into_input`] or [`strip_input`].
+    /// by calling [`into_input`] or [`strip_input`] on it.
     ///
     /// [`URI-reference`]: https://datatracker.ietf.org/doc/html/rfc3986/#section-4.1
     /// [`into_input`]: ParseError::into_input
@@ -272,7 +272,7 @@ impl<'i, 'o, T: BorrowOrShare<'i, 'o, str>> Uri<T> {
 
     /// Returns the optional [scheme] component.
     ///
-    /// Note that the scheme component is **case-insensitive**.
+    /// Note that the scheme component is *case-insensitive*.
     /// See the documentation of [`Scheme`] for more details on comparison.
     ///
     /// [scheme]: https://datatracker.ietf.org/doc/html/rfc3986/#section-3.1
@@ -282,8 +282,10 @@ impl<'i, 'o, T: BorrowOrShare<'i, 'o, str>> Uri<T> {
     /// ```
     /// use fluent_uri::{component::Scheme, Uri};
     ///
+    /// const SCHEME_HTTP: &Scheme = Scheme::new_or_panic("http");
+    ///
     /// let uri = Uri::parse("http://example.com/")?;
-    /// assert_eq!(uri.scheme(), Some(Scheme::new_or_panic("http")));
+    /// assert_eq!(uri.scheme(), Some(SCHEME_HTTP));
     ///
     /// let uri = Uri::parse("/path/to/file")?;
     /// assert_eq!(uri.scheme(), None);