docs(useNamingConvention): add examples and improve explanations

crates/biome_js_analyze/src/lint/style/use_naming_convention.rs

@@ -244,6 +244,48 @@ declare_rule! {
     /// }
     /// ```
     ///
+    /// ## Ignored declarations
+    ///
+    /// Note that some declarations are always ignored.
+    /// You cannot apply a convention to them.
+    /// This is the cas eof:
+    ///
+    /// - Member names that are not identifiers
+    ///
+    ///   ```js,ignore
+    ///   class C {
+    ///     ["not an identifier"]() {}
+    ///   }
+    ///   ```
+    ///
+    /// - Named imports
+    ///
+    ///  ```js,ignore
+    ///   import { an_IMPORT } from "mod"
+    ///   ```
+    ///
+    /// - destructured object properties
+    ///
+    ///   ```js,ignore
+    ///   const { destructed_PROP } = obj;
+    ///   ```
+    ///
+    /// - class member marked with `override`
+    ///
+    ///   ```ts,ignore
+    ///   class C extends B {
+    ///     override overridden_METHOD() {}
+    ///   }
+    ///   ```
+    ///
+    /// - declarations inside an external TypeScript module
+    ///
+    ///   ```ts,ignore
+    ///   declare module "myExternalModule" {
+    ///     export interface my_INTERFACE {}
+    ///   }
+    ///   ```
+    ///
     /// ## Options
     ///
     /// The rule provides several options that are detailed in the following subsections.
@@ -307,7 +349,7 @@ declare_rule! {
     ///
     /// The `conventions` option allows applying custom conventions.
     /// The option takes an array of conventions.
-    /// Every convention is an object that includes a `selector` and some requirements (`match` and `formats`).
+    /// Every convention is an object that includes an optional `selector` and one or more requirements (`match` and `formats`).
     ///
     /// For example, you can enforce the use of [`CONSTANT_CASE`] for global `const` declarations:
     ///
@@ -386,20 +428,115 @@ declare_rule! {
     /// A convention must set at least one requirement among:
     ///
     /// - `match`: a regular expression that the name of the declaration must match.
-    ///   If the regular expression captures a part of the name, then this part is checked against `formats`.
-    ///   Only the first capture is tested. Other captures are ignored.
     /// - `formats`: the string [case] that the name must follow.
     ///   The supported cases are: [`PascalCase`], [`CONSTANT_CASE`], [`camelCase`], and [`snake_case`].
     ///
+    /// If both `match` and `formats` are set, then `formats` is checked against the first capture of the regular expression.
+    /// Only the first capture is tested. Other captures are ignored.
+    /// If nothing is captured, then `formats` is ignored.
+    ///
+    /// In the following example, we check the following conventions:
+    ///
+    /// - A private property starts with `_` and consists of at least two characters
+    /// - The captured name (the name without the leading `_`) is in [`camelCase`].
+    ///
+    /// ```json
+    /// {
+    ///     // ...
+    ///     "options": {
+    ///         "conventions": [
+    ///             {
+    ///                 "selector": {
+    ///                     "kind": "classMember",
+    ///                     "modifiers": ["private"]
+    ///                 },
+    ///                 "match": "_(.+)",
+    ///                 "formats": ["camelCase"]
+    ///             }
+    ///         ]
+    ///     }
+    /// }
+    /// ```
+    ///
     /// If `match` is set and `formats` is unset,
-    /// then the part of the name captured by the regular expression is forwarded to the next convention of the array.
+    /// then the part of the name captured by the regular expression is forwarded to the next conventions of the array.
+    /// In the following example, we require that private class members start with `_` and all class members are in ["camelCase"].
+    ///
+    /// ```json5
+    /// {
+    ///     // ...
+    ///     "options": {
+    ///         "conventions": [
+    ///             {
+    ///                 "selector": {
+    ///                     "kind": "classMember",
+    ///                     "modifiers": ["private"]
+    ///                 },
+    ///                 "match": "_(.+)"
+    ///                 // We don't need to specify `formats` because the capture is forwarded to the next conventions.
+    ///             },
+    ///             {
+    ///                 "selector": {
+    ///                     "kind": "classMember"
+    ///                 },
+    ///                 "formats": ["camelCase"]
+    ///             }
+    ///         ]
+    ///     }
+    /// }
+    /// ```
+    ///
+    /// If a declaration is not selected or if a capture is forwarded while there is no more conventions,
+    /// then the declaration name is verified against the default conventions.
+    /// Because, the default conventions already ensure that class members are in ["camelCase"],
+    /// the previous example can be simplified to:
+    ///
+    /// ```json5
+    /// {
+    ///     // ...
+    ///     "options": {
+    ///         "conventions": [
+    ///             {
+    ///                 "selector": {
+    ///                     "kind": "classMember",
+    ///                     "modifiers": ["private"]
+    ///                 },
+    ///                 "match": "_(.+)"
+    ///                 // We don't need to specify `formats` because the capture is forwarded to the next conventions.
+    ///             }
+    ///             // default conventions
+    ///         ]
+    ///     }
+    /// }
+    /// ```
+    ///
+    /// If the capture is identical to the initial name (it is not a part of the initial name),
+    /// then leading and trailing underscore and dollar signs are trimmed before checking against default conventions.
+    /// In the previous example, the capture is a part of the name because `_` is not included in the capture.
+    ///
+    /// You can reset all default conventions by adding a convention at the end of the array that accepts anything:
+    ///
+    /// ```json5
+    /// {
+    ///     // ...
+    ///     "options": {
+    ///         "conventions": [
+    ///             // your conventions
+    ///             // ...
     ///
-    /// If a declaration is not selected or if a capture is forwarded while there is no more custom conventions,
-    /// Then the declaration is verified against the default convention.
-    /// If a forwarded capture is a part of the original name, then underscore and dollar signs are not trimmed.
+    ///             // Otherwise, accept anything
+    ///             {
+    ///                 "match": ".*"
+    ///             }
+    ///         ]
+    ///     }
+    /// }
+    /// ```
     ///
-    /// In the following example:
+    /// Let's take a more complex example with the following conventions:
     ///
+    /// - Accept variable names `i`, `j`, and check all other names against the next conventions
+    /// - All identifiers must contain at least 2 characters
     /// - We require `private` class members to start with an underscore `_`.
     /// - We require `static readonly` class properties to be in [`CONSTANT_CASE`].
     ///   A `private static readonly` property must also start with an underscore as dictated by the previous convention.
@@ -409,13 +546,22 @@ declare_rule! {
     ///   and to be in [`PascalCase`].
     /// - All other names follow the default conventions
     ///
-    ///```json5
+    /// ```json5
     /// {
     ///     // ...
     ///     "options": {
     ///         "conventions": [
     ///             {
     ///                 "selector": {
+    ///                     "kind": "variable"
+    ///                 },
+    ///                 "match": "[ij]|(.*)"
+    ///             },
+    ///             {
+    ///                 "match": "(.{2,})"
+    ///             },
+    ///             {
+    ///                 "selector": {
     ///                     "kind": "classMember",
     ///                     "modifiers": ["private"]
     ///                 },