From d79aa829468500e6b87f10ff17b05adb1cd24d13 Mon Sep 17 00:00:00 2001
From: Alpha DIALLO <moyodiallo@gmail.com>
Date: Wed, 28 Feb 2024 12:45:08 +0100
Subject: [PATCH] doc: Move glob syntax to dune-glob (#7988)

Signed-off-by: Alpha DIALLO <moyodiallo@gmail.com>
---
 dune-glob.opam                |  2 +-
 dune-project                  |  1 +
 otherlibs/dune-glob/index.mld | 29 +++++++++++++++++++++++++++++
 3 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/dune-glob.opam b/dune-glob.opam
index 4aaaa515c194..57307e8c715a 100644
--- a/dune-glob.opam
+++ b/dune-glob.opam
@@ -14,8 +14,8 @@ depends: [
   "stdune" {= version}
   "dyn"
   "ordering"
+  "odoc" {>= "2.3.0" & with-doc}
   "dune-private-libs" {= version}
-  "odoc" {with-doc}
 ]
 dev-repo: "git+https://github.com/ocaml/dune.git"
 build: [
diff --git a/dune-project b/dune-project
index f3e3f36bc28c..aa741a2cea53 100644
--- a/dune-project
+++ b/dune-project
@@ -131,6 +131,7 @@ execution of the action.
   (stdune (= :version))
   dyn
   ordering
+  (odoc (and (>= 2.3.0) :with-doc))
   (dune-private-libs (= :version)))
  (description "\
 dune-glob provides a parser and interpreter for globs as \
diff --git a/otherlibs/dune-glob/index.mld b/otherlibs/dune-glob/index.mld
index 5e4db9d6f38a..da75dd8ef5d9 100644
--- a/otherlibs/dune-glob/index.mld
+++ b/otherlibs/dune-glob/index.mld
@@ -6,6 +6,35 @@ A {e glob} is a way of referring to a set of files that match a certain
 pattern, such as "files with the [.ml] extension" or "files with [test] in
 their name".
 
+The glob syntax is interpreted as follows:
+- [\<char>] matches exactly [<char>], even if it's a special character
+  ([*], [?], ...).
+- [*] matches any sequence of characters, except if it comes first, in which
+  case it matches any character that is not [.] followed by anything.
+- [**] matches any character that is not [.] followed by anything, except if
+  it comes first, in which case it matches anything.
+- [?] matches any single character.
+- [[<set>]] matches any character that is part of [<set>].
+- [[!<set>]] matches any character that is not part of [<set>].
+- [{<glob1>,<glob2>,...,<globn>}] matches any string that is matched by one of
+  [<glob1>] [<glob2>] etc.
+
+{t
+	| Syntax            | Files matched                      | Files not matched       |
+	|-------------------|------------------------------------|-------------------------|
+	| [ x ]             | [ x ]                              | [ y ]                   |
+	| [ \* ]            | [ * ]                              | [ x ]                   |
+	| [ file*.txt ]     | [ file1.txt ], [ file2.txt ]       | [ f.txt ]               |
+	| [ *.txt ]         | [ f.txt ]                          | [ .hidden.txt ]         |
+	| [ a** ]           | [ aml ]                            | [ a.ml ]                |
+	| [ ** ]            | [ a/b ], [ a.b ]                   | (none)                  |
+	| [ a?.txt ]        | [ a1.txt ], [ a2.txt ]             | [ b1.txt ], [ a10.txt ] |
+	| [ f[xyz].txt ]    | [ fx.txt ], [ fy.txt ], [ fz.txt ] | [ f2.txt ], [ f.txt ]   |
+	| [ f[!xyz].txt ]   | [ f2.txt ], [ fa.txt ]             | [ fx.txt ], [ f.txt ]   |
+	| [ a.{ml,mli} ]    | [ a.ml ], [ a.mli ]                | [ a.txt ], [ b.ml ]     |
+	| [ ../a.{ml,mli} ] | [ ../a.ml ], [ ../a.mli ]          | [ a.ml ]                |
+}
+
 [dune-glob] exposes an abstraction so that we can refer to the first group as
 [*.ml] and the second one as [*test*].