Improve doc and comments

src/encoding/mod.rs

@@ -381,8 +381,10 @@ impl EStr<Path> {
 
     /// Returns an iterator over the [path segments].
     ///
+    /// See the following examples for the exact behavior of this method.
+    ///
     /// The returned iterator does **not** uniquely identify a path
-    /// because it does not output the empty string before a preceding `'/'`.
+    /// because it does not output the empty string before a leading `'/'`.
     /// You may need to check whether the path is [absolute] in addition to calling this method.
     ///
     /// [path segments]: https://datatracker.ietf.org/doc/html/rfc3986/#section-3.3
@@ -393,18 +395,21 @@ impl EStr<Path> {
     /// ```
     /// use fluent_uri::Uri;
     ///
-    /// // An empty path has no segments.
-    /// let uri = Uri::parse("")?;
-    /// assert_eq!(uri.path().segments().next(), None);
-    ///
     /// // Segments are separated by '/'.
-    /// let uri = Uri::parse("a/b/c")?;
-    /// assert!(uri.path().segments().eq(["a", "b", "c"]));
-    ///
-    /// // The empty string before a preceding '/' is not a segment.
+    /// // The empty string before a leading '/' is not a segment.
     /// // However, segments can be empty in the other cases.
     /// let uri = Uri::parse("/path/to//dir/")?;
     /// assert!(uri.path().segments().eq(["path", "to", "", "dir", ""]));
+    ///
+    /// // Segments of an absolute path may equal those of a rootless path.
+    /// let uri_a = Uri::parse("/foo/bar")?;
+    /// let uri_b = Uri::parse("foo/bar")?;
+    /// assert!(uri_a.path().segments().eq(["foo", "bar"]));
+    /// assert!(uri_b.path().segments().eq(["foo", "bar"]));
+    ///
+    /// // An empty path has no segments.
+    /// let uri = Uri::parse("")?;
+    /// assert_eq!(uri.path().segments().next(), None);
     /// # Ok::<_, fluent_uri::error::ParseError>(())
     /// ```
     #[inline]

src/parser.rs

@@ -188,7 +188,7 @@ impl<'a> Reader<'a> {
             match self.read_v6_segment() {
                 Some(Seg::Normal(seg, colon)) => {
                     if colon == (i == 0 || i == ellipsis_i) {
-                        // Preceding colon, triple colons, or no colon.
+                        // Leading colon, triple colons, or no colon.
                         return None;
                     }
                     segs[i] = seg;

tests/parse_ip.rs

@@ -42,7 +42,7 @@ fn test_parse_v4() {
     // octal zero
     assert!(parse_v4("255.0.0.00").is_none());
     assert!(parse_v4("255.0.00.0").is_none());
-    // preceding dot
+    // leading dot
     assert!(parse_v4(".0.0.0.0").is_none());
     // trailing dot
     assert!(parse_v4("0.0.0.0.").is_none());
@@ -103,7 +103,7 @@ fn test_parse_v6() {
     assert!(parse_v6("::1:2:3:4:5:6:7:8").is_none());
     assert!(parse_v6("1:2:3:4::5:6:7:8").is_none());
     assert!(parse_v6("1:2:3:4:5:6:7:8::").is_none());
-    // preceding colon
+    // leading colon
     assert!(parse_v6(":1:2:3:4:5:6:7:8").is_none());
     assert!(parse_v6(":1::1").is_none());
     assert!(parse_v6(":1").is_none());