docs: update BRACES_REGEXP comment

lib/validateConfig.js

@@ -18,17 +18,30 @@ const TEST_DEPRECATED_KEYS = new Map([
 ])
 
 /**
- * Braces with a single value like `*.{js}` are invalid
- * and thus ignored by micromatch. This regex matches all occurrences of
- * two curly braces without a `,` or `..` between them, to make sure
- * users can still accidentally use them without
- * some linters never matching anything. It will further not match
- * escaped braces `\{` `\}`, or if braces contain an escaped comma `\,`.
- * Finally, a dollar sign `${` inhibits brace expansion.
- *
- * For example `.{js,ts}` or `file_{1..10}` are valid but `*.{js}` is not.
+ * A correctly-formed brace expansion must contain unquoted opening and closing braces,
+ * and at least one unquoted comma or a valid sequence expression.
+ * Any incorrectly formed brace expansion is left unchanged.
  *
  * @see https://www.gnu.org/software/bash/manual/html_node/Brace-Expansion.html
+ *
+ * Lint-staged uses `micromatch` for brace expansion, and its behavior is to treat
+ * invalid brace expansions as literal strings, which means they (typically) do not match
+ * anything.
+ *
+ * This RegExp tries to match most cases of invalid brace expansions, so that they can be
+ * detected, warned about, and re-formatted by removing the braces and thus hopefully
+ * matching the files as intended by the user. The only real fix is to remove the incorrect
+ * braces from user configuration, but this is left to the user (after seeing the warning).
+ *
+ * @example <caption>Globs with brace expansions</caption>
+ * - *.{js,tx}         // expanded as *.js, *.ts
+ * - file_{1..10}.css  // expanded as file_1.css, file_2.css, …, file_10.css
+ *
+ * @example <caption>Globs with incorrect brace expansions</caption>
+ * - *.{js}     // should just be *.js
+ * - *.\{js\}   // escaped braces, so they're treated literally
+ * - *.${js}    // dollar-sign inhibits expansion, so treated literally
+ * - *.{js\,ts} // the comma is escaped, so treated literally
  */
 const BRACES_REGEXP = new RegExp(/(?<![\\$])({)(?:(?!(?<!\\),|\.\.).)*?(?<!\\)(})/g)