From e0aa13f392ef9fab7c1d8060e9d8eb0480f87982 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?=
 <ivan.canet@gmail.com>
Date: Sun, 15 Mar 2026 00:57:44 +0100
Subject: [PATCH] test(dsl): Document that the RegExp syntax isn't identical to
 the documentation, yet is still correct

---
 .../kotlin/query/filter/RegexTest.kt          | 41 ++++++++++++++++++-
 1 file changed, 40 insertions(+), 1 deletion(-)

diff --git a/dsl/src/commonTest/kotlin/query/filter/RegexTest.kt b/dsl/src/commonTest/kotlin/query/filter/RegexTest.kt
index 5f32674c..352edd86 100644
--- a/dsl/src/commonTest/kotlin/query/filter/RegexTest.kt
+++ b/dsl/src/commonTest/kotlin/query/filter/RegexTest.kt
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2025, OpenSavvy and contributors.
+ * Copyright (c) 2025-2026, OpenSavvy and contributors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,6 +19,45 @@ package opensavvy.ktmongo.dsl.query.filter
 import opensavvy.ktmongo.dsl.query.shouldBeBson
 import opensavvy.prepared.runner.testballoon.preparedSuite
 
+/**
+ * The examples [in the documentation](https://www.mongodb.com/docs/manual/reference/operator/query/regex/) use syntax:
+ * ```MongoDB-JSON
+ * {
+ *    "field": {
+ *        "$regex": "<pattern>",
+ *        "$options": "<options>"
+ *    }
+ * }
+ * ```
+ * and
+ * ```MongoDB-JSON
+ * {
+ *    "field": {
+ *        "$regex": /<pattern>/<options>
+ *    }
+ * }
+ * ```
+ *
+ * The first pattern uses a nested document, the second uses the native BSON RegExp type.
+ * However, the syntax shown isn't part of the BSON standard, it is specific to the JS drivers.
+ *
+ * According to the [official BSON test suite](https://github.com/mongodb/specifications/blob/master/source/bson-corpus/tests/regex.json),
+ * the native RexExp should be displayed:
+ * ```MongoDB-JSON
+ * {
+ *     "field": {
+ *         "$regex": {
+ *             "$regularExpression": {
+ *                 "pattern": "<pattern>",
+ *                 "options": "<options>"
+ *             }
+ *         }
+ *     }
+ * }
+ * ```
+ * However, this is misleading because it looks like a nested object, when it isn't, it's the JSON representation of the native type.
+ * Copy-pasting this JSON request into a MongoDB editor will not work.
+ */
 val RegexTest by preparedSuite {
 	suite("Regex") {
 		test("Basic usage") {
-- 
2.51.2