Tweak docs

idna/src/deprecated.rs

@@ -16,6 +16,7 @@ use alloc::string::String;
 use crate::uts46::*;
 use crate::Errors;
 
+/// Deprecated. Use the crate-top-level functions or [`Uts46`].
 #[derive(Default)]
 #[deprecated]
 pub struct Idna {
@@ -27,7 +28,7 @@ impl Idna {
         Self { config }
     }
 
-    /// http://www.unicode.org/reports/tr46/#ToASCII
+    /// [UTS 46 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> {
         match Uts46::new().process(
@@ -56,7 +57,7 @@ impl Idna {
         }
     }
 
-    /// http://www.unicode.org/reports/tr46/#ToUnicode
+    /// [UTS 46 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> {
         match Uts46::new().process(
@@ -78,6 +79,7 @@ impl Idna {
     }
 }
 
+/// Deprecated configuration API.
 #[derive(Clone, Copy)]
 #[must_use]
 #[deprecated]
@@ -87,7 +89,7 @@ pub struct Config {
     check_hyphens: bool,
 }
 
-/// The defaults are that of https://url.spec.whatwg.org/#idna
+/// The defaults are that of _beStrict=false_ in the [WHATWG URL Standard](https://url.spec.whatwg.org/#idna)
 impl Default for Config {
     fn default() -> Self {
         Config {
@@ -100,38 +102,67 @@ impl Default for Config {
 }
 
 impl Config {
+    /// Whether to enforce STD3 or WHATWG URL Standard ASCII deny list.
+    ///
+    /// `true` for STD3, `false` for WHATWG.
+    ///
+    /// Note that `true` rejects pseudo-hosts used by various TXT record-based protocols.
+    ///
+    /// Must be set to the same value as [`Config::check_hyphens`].
     #[inline]
     pub fn use_std3_ascii_rules(mut self, value: bool) -> Self {
         self.use_std3_ascii_rules = value;
         self
     }
 
+    /// Obsolete method retained to ease migration. The argument must be `false`.
+    ///
+    /// Panics
+    ///
+    /// If the argument is `true`.
     #[inline]
     #[allow(unused_mut)]
     pub fn transitional_processing(mut self, value: bool) -> Self {
         assert!(!value, "Transitional processing is no longer supported");
         self
     }
 
+    /// Whether the _VerifyDNSLength_ operation should be performed
+    /// by `to_ascii`.
     #[inline]
     pub fn verify_dns_length(mut self, value: bool) -> Self {
         self.verify_dns_length = value;
         self
     }
 
+    /// Whether to enforce IETF rules for hyphen placement.
+    ///
+    /// `true` to deny hyphens in the first, last, third, and fourth
+    /// position of a label. `false` to not enforce.
+    ///
+    /// Note that `true` rejects real-world names, including YouTube CDN nodes
+    /// and some GitHub user pages.
+    ///
+    /// Must be set to the same value as [`Config::use_std3_ascii_rules`].
     #[inline]
     pub fn check_hyphens(mut self, value: bool) -> Self {
         self.check_hyphens = value;
         self
     }
 
+    /// Obsolete method retained to ease migration. The argument must be `false`.
+    ///
+    /// Panics
+    ///
+    /// If the argument is `true`.
     #[inline]
     #[allow(unused_mut)]
     pub fn use_idna_2008_rules(mut self, value: bool) -> Self {
         assert!(!value, "IDNA 2008 rules are no longer supported");
         self
     }
 
+    /// Compute strictness
     fn strictness(&self) -> Strictness {
         assert_eq!(self.check_hyphens, self.use_std3_ascii_rules, "Setting check_hyphens and use_std3_ascii_rules to different values is no longer supported");
         if self.use_std3_ascii_rules {
@@ -141,14 +172,14 @@ impl Config {
         }
     }
 
-    /// http://www.unicode.org/reports/tr46/#ToASCII
+    /// [UTS 46 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
+    /// [UTS 46 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());

idna/src/uts46.rs

@@ -185,7 +185,7 @@ const PUNYCODE_PREFIX: u32 =
 const PUNYCODE_PREFIX_MASK: u32 = (0xFF << 24) | (0xFF << 16) | (0xDF << 8) | 0xDF;
 
 #[inline(always)]
-pub fn has_punycode_prefix(slice: &[u8]) -> bool {
+fn has_punycode_prefix(slice: &[u8]) -> bool {
     if slice.len() < 4 {
         return false;
     }
@@ -338,6 +338,7 @@ fn classify_for_punycode(label: &[char]) -> PunycodeClassification {
 
 /// The strictness profile to be applied.
 #[derive(PartialEq, Eq, Copy, Clone)]
+#[non_exhaustive]
 pub enum Strictness {
     /// The _beStrict=false_ option from the WHATWG URL Standard for
     /// practical usage.
@@ -355,6 +356,7 @@ pub enum Strictness {
 
 /// Policy for customizing behavior in case of an error.
 #[derive(PartialEq, Eq, Copy, Clone)]
+#[non_exhaustive]
 pub enum ErrorPolicy {
     /// Return as early as possible without producing output in case of error.
     FailFast,
@@ -450,6 +452,7 @@ pub fn verify_dns_length(domain_name: &str) -> bool {
     true
 }
 
+/// An implementation of UTS #46.
 pub struct Uts46 {
     mapper: Uts46Mapper,
     canonical_combining_class: CanonicalCombiningClassMap,
@@ -460,6 +463,8 @@ pub struct Uts46 {
 
 impl Uts46 {
     // XXX Should this be behind a `compiled_data` feature?
+
+    /// Constructor using data compiled into the binary.
     pub const fn new() -> Self {
         Self {
             mapper: Uts46Mapper::new(),
@@ -580,9 +585,9 @@ impl Uts46 {
         }
     }
 
-    /// The lower-level function that [`to_ascii`], [`to_unicode`], and [`to_user_interface`] are
-    /// built on to allow support for output types other than `Cow<'a, str>` (e.g. string types
-    /// in a non-Rust programming language).
+    /// The lower-level function that [`Uts46::to_ascii`], [`Uts46::to_unicode`], and
+    /// [`Uts46::to_user_interface`] are built on to allow support for output types other
+    /// than `Cow<'a, str>` (e.g. string types in a non-Rust programming language).
     ///
     /// # Arguments
     ///