From 36073a3d95ba2cb5aa5286f14aca7fa1564301a8 Mon Sep 17 00:00:00 2001
From: cyqsimon <28627918+cyqsimon@users.noreply.github.com>
Date: Sun, 5 Nov 2023 22:46:53 +0800
Subject: [PATCH] Document another rule ignore condition

---
 src/syntax_mapping.rs                 | 11 ++++++-----
 src/syntax_mapping/builtins/README.md |  3 ++-
 2 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/src/syntax_mapping.rs b/src/syntax_mapping.rs
index 442fb6dd..b7a13979 100644
--- a/src/syntax_mapping.rs
+++ b/src/syntax_mapping.rs
@@ -61,9 +61,8 @@ impl<'a> SyntaxMapping<'a> {
     ///
     /// Builtin mappings' `GlobMatcher`s are lazily compiled.
     ///
-    /// Note that this function ignores builtin mappings that are invalid under
-    /// the current environment (i.e. their rules require an environment
-    /// variable that is unset).
+    /// Note that this function only returns mappings that are valid under the
+    /// current environment. For details see [`Self::builtin_mappings`].
     pub fn all_mappings(&self) -> impl Iterator<Item = (&GlobMatcher, &MappingTarget<'a>)> {
         self.custom_mappings()
             .iter()
@@ -83,8 +82,10 @@ impl<'a> SyntaxMapping<'a> {
     ///
     /// The `GlabMatcher`s are lazily compiled.
     ///
-    /// If a mapping rule requires an environment variable that is unset, it
-    /// will be ignored.
+    /// Mappings that are invalid under the current environment (i.e. rule
+    /// requires environment variable(s) that is unset, or the joined string
+    /// after variable(s) replacement is not a valid glob expression) are
+    /// ignored.
     pub fn builtin_mappings(
         &self,
     ) -> impl Iterator<Item = (&'static GlobMatcher, &'static MappingTarget<'static>)> {
diff --git a/src/syntax_mapping/builtins/README.md b/src/syntax_mapping/builtins/README.md
index 47a7a9e3..666b7adc 100644
--- a/src/syntax_mapping/builtins/README.md
+++ b/src/syntax_mapping/builtins/README.md
@@ -76,7 +76,8 @@ could write something like this:
 ```
 
 If any environment variable replacement in a rule fails (for example when a
-variable is unset), the entire rule will be ignored.
+variable is unset), or if the glob string after replacements is invalid, the
+entire rule will be ignored.
 
 ### Explicitly mapping to unknown