doc: improve documentation of common_prefix() and pattern_matching_relative_path().

Author: Byron

gix-pathspec/src/lib.rs

@@ -93,9 +93,12 @@ pub struct Pattern {
     pub attributes: Vec<gix_attributes::Assignment>,
     /// If `true`, we are a special Nil pattern and always match.
     nil: bool,
-    /// The length of bytes in `path` that belong to the prefix, which will always be matched case-insensitively.
+    /// The length of bytes in `path` that belong to the prefix, which will always be matched case-sensitively
+    /// on case-sensitive filesystems.
+    ///
     /// That way, even though pathspecs are applied from the top, we can emulate having changed directory into
-    /// a specific sub-directory in a case-sensitive file-system.
+    /// a specific sub-directory in a case-sensitive file-system, even if the rest of the pathspec can be set to
+    /// match case-insensitively.
     /// Is set by [Pattern::normalize()].
     prefix_len: usize,
 }

gix-pathspec/src/search/matching.rs

@@ -8,7 +8,7 @@ use crate::{
 
 impl Search {
     /// Return the first [`Match`] of `relative_path`, or `None`.
-    /// `is_dir` is true if `relative_path` is a directory.
+    /// `is_dir` is `true` if `relative_path` is a directory.
     /// `attributes` is called as `attributes(relative_path, case, is_dir, outcome) -> has_match` to obtain for attributes for `relative_path`, if
     /// the underlying pathspec defined an attribute filter, to be stored in `outcome`, returning true if there was a match.
     /// All attributes of the pathspec have to be present in the defined value for the pathspec to match.

gix-pathspec/src/search/mod.rs

@@ -30,8 +30,10 @@ impl Search {
     /// Return the portion of the prefix among all of the pathspecs involved in this search, or an empty string if
     /// there is none. It doesn't have to end at a directory boundary though, nor does it denote a directory.
     ///
-    /// Note that the common_prefix can be matched case-insensitively, which makes it useful to skip large portions of input.
-    /// Further, excluded pathspecs don't participate which makes this common prefix inclusive.
+    /// Note that the common_prefix is always matched case-sensitively, and it is useful to skip large portions of input.
+    /// Further, excluded pathspecs don't participate which makes this common prefix inclusive. To work correclty though,
+    /// one will have to additionally match paths that have the common prefix with that pathspec itself to assure it is
+    /// not excluded.
     pub fn common_prefix(&self) -> &BStr {
         self.patterns
             .iter()