From 67ef492460f3202c033676e9b9039f0d5ad8a13f Mon Sep 17 00:00:00 2001 From: Victorien Elvinger Date: Mon, 24 Jun 2024 13:01:25 +0200 Subject: [PATCH 1/2] docs(useNamingConvention): add examples and improve explanations --- .../src/lint/style/use_naming_convention.rs | 164 +++++++++++++++++- 1 file changed, 155 insertions(+), 9 deletions(-) diff --git a/crates/biome_js_analyze/src/lint/style/use_naming_convention.rs b/crates/biome_js_analyze/src/lint/style/use_naming_convention.rs index 5483cc0d0f52..c0e3fef0368d 100644 --- a/crates/biome_js_analyze/src/lint/style/use_naming_convention.rs +++ b/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"] /// }, From 6aba917ea34dd3ebcc6c5d72fd04d34a7cb17cca Mon Sep 17 00:00:00 2001 From: Victorien Elvinger Date: Mon, 24 Jun 2024 14:54:16 +0200 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Emanuele Stoppa --- .../src/lint/style/use_naming_convention.rs | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/crates/biome_js_analyze/src/lint/style/use_naming_convention.rs b/crates/biome_js_analyze/src/lint/style/use_naming_convention.rs index c0e3fef0368d..65bbe218eb2e 100644 --- a/crates/biome_js_analyze/src/lint/style/use_naming_convention.rs +++ b/crates/biome_js_analyze/src/lint/style/use_naming_convention.rs @@ -440,7 +440,7 @@ declare_rule! { /// - A private property starts with `_` and consists of at least two characters /// - The captured name (the name without the leading `_`) is in [`camelCase`]. /// - /// ```json + /// ```json5 /// { /// // ... /// "options": { @@ -486,9 +486,9 @@ declare_rule! { /// } /// ``` /// - /// If a declaration is not selected or if a capture is forwarded while there is no more conventions, + /// If a declaration is not selected or if a capture is forwarded while there are 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"], + /// Because the default conventions already ensure that class members are in ["camelCase"], /// the previous example can be simplified to: /// /// ```json5 @@ -511,7 +511,7 @@ declare_rule! { /// ``` /// /// 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. + /// then, leading and trailing underscore and dollar signs are trimmed before being checked 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: @@ -535,8 +535,8 @@ declare_rule! { /// /// 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 + /// - Accept variable names `i`, `j`, and check all other names against the next conventions. + /// - All identifiers must contain at least two 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.