docs for git-glob (#301)

git-glob/src/lib.rs

@@ -1,5 +1,6 @@
 #![forbid(unsafe_code)]
-#![deny(rust_2018_idioms)]
+#![deny(rust_2018_idioms, missing_docs)]
+//! Provide glob [`Patterns`][Pattern] for matching against paths or anything else.
 
 use bstr::BString;
 
@@ -20,8 +21,10 @@ pub struct Pattern {
     pub base_path: Option<BString>,
 }
 
+///
 pub mod pattern;
 
+///
 pub mod wildmatch;
 pub use wildmatch::function::wildmatch;
 

git-glob/src/pattern.rs

@@ -4,6 +4,12 @@ use bstr::{BStr, BString, ByteSlice};
 use crate::{pattern, wildmatch, Pattern};
 
 bitflags! {
+    /// Information about a [`Pattern`].
+    ///
+    /// Its main purpose is to accelerate pattern matching, or to negate the match result or to
+    /// keep special rules only applicable when matching paths.
+    ///
+    /// The mode is typically created when parsing the pattern by inspecting it and isn't typically handled by the user.
     #[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
     pub struct Mode: u32 {
         /// The pattern does not contain a sub-directory and - it doesn't contain slashes after removing the trailing one.
@@ -19,6 +25,9 @@ bitflags! {
     }
 }
 
+/// Describes whether to match a path case sensitively or not.
+///
+/// Used in [Pattern::matches_repo_relative_path()].
 pub enum Case {
     /// The case affects the match
     Sensitive,
@@ -27,6 +36,7 @@ pub enum Case {
 }
 
 impl Pattern {
+    /// Parse the given `text` as pattern, or return `None` if `text` was empty.
     pub fn from_bytes(text: &[u8]) -> Option<Self> {
         crate::parse::pattern(text).map(|(text, mode, first_wildcard_pos)| Pattern {
             text,
@@ -61,6 +71,8 @@ impl Pattern {
     /// `basename_start_pos` is the index at which the `path`'s basename starts.
     ///
     /// Lastly, `case` folding can be configured as well.
+    ///
+    /// Note that this method uses shortcuts to accelerate simple patterns.
     pub fn matches_repo_relative_path<'a>(
         &self,
         path: impl Into<&'a BStr>,
@@ -113,6 +125,12 @@ impl Pattern {
         }
     }
 
+    /// See if `value` matches this pattern in the given `mode`.
+    ///
+    /// `mode` can identify `value` as path which won't match the slash character, and can match
+    /// strings with cases ignored as well. Note that the case folding performed here is ASCII only.
+    ///
+    /// Note that this method uses some shortcuts to accelerate simple patterns.
     pub fn matches<'a>(&self, value: impl Into<&'a BStr>, mode: wildmatch::Mode) -> bool {
         let value = value.into();
         match self.first_wildcard_pos {

git-glob/src/wildmatch.rs

@@ -1,5 +1,6 @@
 use bitflags::bitflags;
 bitflags! {
+    /// The match mode employed in [`Pattern::matches()`][crate::Pattern::matches()].
     #[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
     pub struct Mode: u8 {
         /// Let globs not match the slash `/` literal.
@@ -334,6 +335,9 @@ pub(crate) mod function {
         t.next().map(|_| NoMatch).unwrap_or(Match)
     }
 
+    /// Employ pattern matching to see if `value` matches `pattern`.
+    ///
+    /// `mode` can be used to adjust the way the matching is performed.
     pub fn wildmatch(pattern: &BStr, value: &BStr, mode: Mode) -> bool {
         match_recursive(pattern, value, mode) == Result::Match
     }

git-repository/Cargo.toml

@@ -49,7 +49,7 @@ max-performance = ["git-features/parallel", "git-features/zlib-ng-compat", "git-
 local-time-support = ["git-actor/local-time-support"]
 ## Re-export stability tier 2 crates for convenience and make `Repository` struct fields with types from these crates publicly accessible.
 ## Doing so is less stable than the stability tier 1 that `git-repository` is a member of.
-unstable = ["git-index", "git-worktree", "git-mailmap"]
+unstable = ["git-index", "git-worktree", "git-mailmap", "git-glob"]
 ## Print debugging information about usage of object database caches, useful for tuning cache sizes.
 cache-efficiency-debug = ["git-features/cache-efficiency-debug"]
 
@@ -78,6 +78,7 @@ git-mailmap = { version = "^0.1.0", path = "../git-mailmap", optional = true }
 git-features = { version = "^0.20.0", path = "../git-features", features = ["progress"] }
 
 # unstable only
+git-glob = { version = "^0.1.0", path = "../git-glob", optional = true }
 git-index = { version = "^0.2.0", path = "../git-index", optional = true }
 git-worktree = { version = "^0.1.0", path = "../git-worktree", optional = true }
 

git-repository/src/lib.rs

@@ -88,6 +88,7 @@
 //! * [`actor`]
 //! * [`bstr`][bstr]
 //! * [`index`]
+//! * [`glob`]
 //! * [`worktree`]
 //! * [`mailmap`]
 //! * [`objs`]
@@ -126,6 +127,8 @@ pub use git_diff as diff;
 use git_features::threading::OwnShared;
 #[cfg(feature = "unstable")]
 pub use git_features::{parallel, progress, progress::Progress, threading};
+#[cfg(all(feature = "unstable", feature = "git-glob"))]
+pub use git_glob as glob;
 pub use git_hash as hash;
 #[doc(inline)]
 #[cfg(all(feature = "unstable", feature = "git-index"))]