From 4dfd78559ba91c30834636bbb1da5e5b35d761ef Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Arg=C3=A9rus?= <external.john.argerus2@de.bosch.com>
Date: Tue, 5 Sep 2023 17:39:51 +0200
Subject: [PATCH] Add wildcard matching doc (#639)

---
 doc/wildcard_matching.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)
 create mode 100644 doc/wildcard_matching.md

diff --git a/doc/wildcard_matching.md b/doc/wildcard_matching.md
new file mode 100644
index 000000000..f86ee6dd1
--- /dev/null
+++ b/doc/wildcard_matching.md
@@ -0,0 +1,26 @@
+### Matching rules
+
+* An empty pattern "" will match any signal.
+* A pattern without any asterisk - a path in other words - matches either a signal directly or any signal that is a direct or indirect child of the branch with that path.
+* An asterisk "`*`" at the end of a pattern will match any signal that is a direct child of the branch(es) identified by the preceding pattern.
+* A double asterisk "`**`" at the end of a pattern matches any signal that is a direct or indirect child of the branch(es) identified by the preceding pattern.
+* An asterisk "`*`" in the middle (or beginning) of a pattern matches any signal that has a branch (of any name) at that position.
+* A double asterisk "`**`" in the middle (or beginning) of a pattern matches any signal that has zero or more branches at that position.
+
+### Examples
+
+| Path                | Matches                              |
+|---------------------|--------------------------------------|
+| `""`                | Everything                           |
+| `"Vehicle"`         | Everything starting with `Vehicle`   |
+| `"Vehicle.Cabin.Sunroof"` | `Vehicle.Cabin.Sunroof.Position`<br>`Vehicle.Cabin.Sunroof.Shade.Position`<br>`Vehicle.Cabin.Sunroof.Shade.Switch`<br>`Vehicle.Cabin.Sunroof.Switch` |
+| `"Vehicle.Cabin.Sunroof.**"` | `Vehicle.Cabin.Sunroof.Position`<br>`Vehicle.Cabin.Sunroof.Shade.Position`<br>`Vehicle.Cabin.Sunroof.Shade.Switch`<br>`Vehicle.Cabin.Sunroof.Switch`  |
+| `"Vehicle.Cabin.Sunroof.*"` | `Vehicle.Cabin.Sunroof.Position`<br>`Vehicle.Cabin.Sunroof.Switch`  |
+| `"Vehicle.Cabin.Sunroof.*.Position"` | `Vehicle.Cabin.Sunroof.Shade.Position` |
+| `"**.Sunroof.*.Position"` | `Vehicle.Cabin.Sunroof.Shade.Position` |
+| `"*.*.*.*.Position"` | `Vehicle.Cabin.Sunroof.Shade.Position` |
+| `"Vehicle.Cabin.Sunroof.**.Position"` | `Vehicle.Cabin.Sunroof.Position`<br>`Vehicle.Cabin.Sunroof.Shade.Position` |
+| `"**.Sunroof"`      | Nothing |
+| `"**.Sunroof.**"` | `Vehicle.Cabin.Sunroof.Position`<br>`Vehicle.Cabin.Sunroof.Shade.Position`<br>`Vehicle.Cabin.Sunroof.Shade.Switch`<br>`Vehicle.Cabin.Sunroof.Switch`  |
+| `"*.Sunroof"`       | Nothing|
+| `"Sunroof"`         | Nothing|