From d974e427fdebc37241d29aedbb719f0994019e95 Mon Sep 17 00:00:00 2001 From: sanggggg <37951125+sanggggg@users.noreply.github.com> Date: Mon, 30 Jan 2023 09:40:27 +0900 Subject: [PATCH 1/5] docs: fix trailing comma notes --- docs/rules/standard.md | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/docs/rules/standard.md b/docs/rules/standard.md index ce4acda8db..cd4d9521de 100644 --- a/docs/rules/standard.md +++ b/docs/rules/standard.md @@ -184,6 +184,16 @@ Consistent removal (default) or adding of trailing comma's on call site. * It makes it easy to add and reorder elements – there is no need to add or delete the comma if you manipulate elements. * It simplifies code generation, for example, for object initializers. The last element can also have a comma. +!!! note + Trailing comma on call site is automatically disabled if [Wrapping](#wrapping) rule (before 0.48.0, [Indentation](#indentation) rule) is disabled. Because it cannot provide proper formatting with unwrapped calls. (see [Dependencies](./dependencies.md)) + + ```kotlin + processFoo(Foo( + a = 3, + b = 4, + ),) // it's weird to insert "," between unwrapped (continuated) parenthesis + ``` + Rule id: `trailing-comma-on-call-site` ## Trailing comma on declaration site @@ -191,10 +201,10 @@ Rule id: `trailing-comma-on-call-site` Consistent removal (default) or adding of trailing comma's on declaration site. !!! important -KtLint uses the IntelliJ IDEA `.editorconfig` property `ij_kotlin_allow_trailing_comma` to configure the rule. When this property is enabled, KtLint *enforces* the usage of the trailing comma at declaration site while IntelliJ IDEA default formatter only *allows* to use the trailing comma but leaves it to the developer's discretion to actually use it (or not). KtLint values *consistent* formatting more than a per-situation decision. + KtLint uses the IntelliJ IDEA `.editorconfig` property `ij_kotlin_allow_trailing_comma` to configure the rule. When this property is enabled, KtLint *enforces* the usage of the trailing comma at declaration site while IntelliJ IDEA default formatter only *allows* to use the trailing comma but leaves it to the developer's discretion to actually use it (or not). KtLint values *consistent* formatting more than a per-situation decision. !!! note -In KtLint 0.48.x the default value for using the trailing comma on declaration site has been changed to `true` except when codestyle `android` is used. + In KtLint 0.48.x the default value for using the trailing comma on declaration site has been changed to `true` except when codestyle `android` is used. The Kotlin coding conventions](https://kotlinlang.org/docs/reference/coding-conventions.html#names-for-test-methods) encourages the usage of trailing comma's on the declaration site, but leaves it to the developer's discretion to use trailing comma's on the call site. But next to this, it also states that usage of trailing commas has several benefits: @@ -202,6 +212,16 @@ In KtLint 0.48.x the default value for using the trailing comma on declaration s * It makes it easy to add and reorder elements – there is no need to add or delete the comma if you manipulate elements. * It simplifies code generation, for example, for object initializers. The last element can also have a comma. +!!! note + Trailing comma on declaration site is automatically disabled if [Wrapping](#wrapping) rule (before 0.48.0, [Indentation](#indentation) rule) is disabled. Because it cannot provide proper formatting with unwrapped declarations. (see [Dependencies](./dependencies.md)) + + ```kotlin + class FooWrapper(val foo: Foo = Foo( + a = 3, + b = 4, + ),) // it's weird to insert "," between unwrapped (continuated) parenthesis + ``` + Rule id: `trailing-comma-on-declaration-site` ## Wrapping From b6ace52da05c80b3c3a24b1efe9c16ddf3fbe207 Mon Sep 17 00:00:00 2001 From: paul-dingemans Date: Mon, 30 Jan 2023 18:24:39 +0100 Subject: [PATCH 2/5] Improve documentation --- docs/rules/standard.md | 43 +++++++++++++++++++++++++++++++----------- 1 file changed, 32 insertions(+), 11 deletions(-) diff --git a/docs/rules/standard.md b/docs/rules/standard.md index cd4d9521de..c8189bbef7 100644 --- a/docs/rules/standard.md +++ b/docs/rules/standard.md @@ -178,22 +178,33 @@ Consistent removal (default) or adding of trailing comma's on call site. !!! note In KtLint 0.48.x the default value for using the trailing comma on call site has been changed to `true` except when codestyle `android` is used. - Although the Kotlin coding conventions](https://kotlinlang.org/docs/reference/coding-conventions.html#names-for-test-methods) leaves it to the developer's discretion to use trailing comma's on the call site, it also states that usage of trailing commas has several benefits: + Although the [Kotlin coding conventions](https://kotlinlang.org/docs/reference/coding-conventions.html#names-for-test-methods) leaves it to the developer's discretion to use trailing comma's on the call site, it also states that usage of trailing commas has several benefits: * It makes version-control diffs cleaner – as all the focus is on the changed value. * It makes it easy to add and reorder elements – there is no need to add or delete the comma if you manipulate elements. * It simplifies code generation, for example, for object initializers. The last element can also have a comma. -!!! note - Trailing comma on call site is automatically disabled if [Wrapping](#wrapping) rule (before 0.48.0, [Indentation](#indentation) rule) is disabled. Because it cannot provide proper formatting with unwrapped calls. (see [Dependencies](./dependencies.md)) +=== "[:material-heart:](#) Ktlint" + + ```kotlin + class FooWrapper(Foo( + a = 3, + b = 4, // Trailing comma enforced + )) // No trailing comma enforced because of continuated parenthesis + ``` +=== "[:material-heart-off-outline:](#) Disallowed" ```kotlin - processFoo(Foo( + class FooWrapper(Foo( a = 3, - b = 4, - ),) // it's weird to insert "," between unwrapped (continuated) parenthesis + b = 4 // Trailing comma is missing + ),) // No trailing comma expected ``` +!!! note + Trailing comma on call site is automatically disabled if the [Wrapping](#wrapping) rule (or, before version `0.45.0`, the [Indentation](#indentation) rule) is disabled or not loaded (see [dependencies](./dependencies.md)). + + Rule id: `trailing-comma-on-call-site` ## Trailing comma on declaration site @@ -206,22 +217,32 @@ Consistent removal (default) or adding of trailing comma's on declaration site. !!! note In KtLint 0.48.x the default value for using the trailing comma on declaration site has been changed to `true` except when codestyle `android` is used. - The Kotlin coding conventions](https://kotlinlang.org/docs/reference/coding-conventions.html#names-for-test-methods) encourages the usage of trailing comma's on the declaration site, but leaves it to the developer's discretion to use trailing comma's on the call site. But next to this, it also states that usage of trailing commas has several benefits: + The [Kotlin coding conventions](https://kotlinlang.org/docs/reference/coding-conventions.html#names-for-test-methods) encourages the usage of trailing comma's on the declaration site, but leaves it to the developer's discretion to use trailing comma's on the call site. But next to this, it also states that usage of trailing commas has several benefits: * It makes version-control diffs cleaner – as all the focus is on the changed value. * It makes it easy to add and reorder elements – there is no need to add or delete the comma if you manipulate elements. * It simplifies code generation, for example, for object initializers. The last element can also have a comma. -!!! note - Trailing comma on declaration site is automatically disabled if [Wrapping](#wrapping) rule (before 0.48.0, [Indentation](#indentation) rule) is disabled. Because it cannot provide proper formatting with unwrapped declarations. (see [Dependencies](./dependencies.md)) +=== "[:material-heart:](#) Ktlint" + + ```kotlin + class FooWrapper(val foo: Foo = Foo( + a = 3, + b = 4, // Trailing comma enforced + )) // No trailing comma enforced because of continuated parenthesis + ``` +=== "[:material-heart-off-outline:](#) Disallowed" ```kotlin class FooWrapper(val foo: Foo = Foo( a = 3, - b = 4, - ),) // it's weird to insert "," between unwrapped (continuated) parenthesis + b = 4 // Trailing comma is missing + ),) // No trailing comma expected ``` +!!! note + Trailing comma on declaration site is automatically disabled if the [Wrapping](#wrapping) rule (or, before version `0.45.0`, the [Indentation](#indentation) rule) is disabled or not loaded (see [dependencies](./dependencies.md)). + Rule id: `trailing-comma-on-declaration-site` ## Wrapping From 616376a2715382608631811f82f000c2dfd20fcd Mon Sep 17 00:00:00 2001 From: sanggggg Date: Tue, 31 Jan 2023 21:55:39 +0900 Subject: [PATCH 3/5] docs: rollback version should use indent from 0.45.0 to 0.48.0 --- docs/rules/standard.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/rules/standard.md b/docs/rules/standard.md index c8189bbef7..f44f721c1e 100644 --- a/docs/rules/standard.md +++ b/docs/rules/standard.md @@ -202,7 +202,7 @@ Consistent removal (default) or adding of trailing comma's on call site. ``` !!! note - Trailing comma on call site is automatically disabled if the [Wrapping](#wrapping) rule (or, before version `0.45.0`, the [Indentation](#indentation) rule) is disabled or not loaded (see [dependencies](./dependencies.md)). + Trailing comma on call site is automatically disabled if the [Wrapping](#wrapping) rule (or, before version `0.48.0`, the [Indentation](#indentation) rule) is disabled or not loaded (see [dependencies](./dependencies.md)). Rule id: `trailing-comma-on-call-site` @@ -241,7 +241,7 @@ Consistent removal (default) or adding of trailing comma's on declaration site. ``` !!! note - Trailing comma on declaration site is automatically disabled if the [Wrapping](#wrapping) rule (or, before version `0.45.0`, the [Indentation](#indentation) rule) is disabled or not loaded (see [dependencies](./dependencies.md)). + Trailing comma on declaration site is automatically disabled if the [Wrapping](#wrapping) rule (or, before version `0.48.0`, the [Indentation](#indentation) rule) is disabled or not loaded (see [dependencies](./dependencies.md)). Rule id: `trailing-comma-on-declaration-site` From 0e0ad028dd744b6c0d0f28a7eae1e08b77746711 Mon Sep 17 00:00:00 2001 From: sanggggg Date: Tue, 31 Jan 2023 21:59:29 +0900 Subject: [PATCH 4/5] docs: more description about reason why disabled --- docs/rules/standard.md | 73 ++++++++++++++++++++++-------------------- 1 file changed, 39 insertions(+), 34 deletions(-) diff --git a/docs/rules/standard.md b/docs/rules/standard.md index f44f721c1e..f1a608986c 100644 --- a/docs/rules/standard.md +++ b/docs/rules/standard.md @@ -184,25 +184,27 @@ Consistent removal (default) or adding of trailing comma's on call site. * It makes it easy to add and reorder elements – there is no need to add or delete the comma if you manipulate elements. * It simplifies code generation, for example, for object initializers. The last element can also have a comma. -=== "[:material-heart:](#) Ktlint" +!!! note + Trailing comma on call site is automatically disabled if the [Wrapping](#wrapping) rule (or, before version `0.45.0`, the [Indentation](#indentation) rule) is disabled or not loaded. Because it cannot provide proper formatting with unwrapped calls. (see [dependencies](./dependencies.md)). - ```kotlin - class FooWrapper(Foo( - a = 3, - b = 4, // Trailing comma enforced - )) // No trailing comma enforced because of continuated parenthesis - ``` -=== "[:material-heart-off-outline:](#) Disallowed" + === "[:material-heart:](#) Trailing comma with wrapping" - ```kotlin - class FooWrapper(Foo( - a = 3, - b = 4 // Trailing comma is missing - ),) // No trailing comma expected - ``` + ```kotlin + FooWrapper( + Foo( + a = 3, + b = 4, + ), + ) + ``` + === "[:material-heart-off-outline:](#) Trailing comma without wrapping" -!!! note - Trailing comma on call site is automatically disabled if the [Wrapping](#wrapping) rule (or, before version `0.48.0`, the [Indentation](#indentation) rule) is disabled or not loaded (see [dependencies](./dependencies.md)). + ```kotlin + FooWrapper(Foo( + a = 3, + b = 4, + ),) // it's weird to insert "," between unwrapped (continued) parenthesis + ``` Rule id: `trailing-comma-on-call-site` @@ -223,25 +225,28 @@ Consistent removal (default) or adding of trailing comma's on declaration site. * It makes it easy to add and reorder elements – there is no need to add or delete the comma if you manipulate elements. * It simplifies code generation, for example, for object initializers. The last element can also have a comma. -=== "[:material-heart:](#) Ktlint" - - ```kotlin - class FooWrapper(val foo: Foo = Foo( - a = 3, - b = 4, // Trailing comma enforced - )) // No trailing comma enforced because of continuated parenthesis - ``` -=== "[:material-heart-off-outline:](#) Disallowed" - - ```kotlin - class FooWrapper(val foo: Foo = Foo( - a = 3, - b = 4 // Trailing comma is missing - ),) // No trailing comma expected - ``` - !!! note - Trailing comma on declaration site is automatically disabled if the [Wrapping](#wrapping) rule (or, before version `0.48.0`, the [Indentation](#indentation) rule) is disabled or not loaded (see [dependencies](./dependencies.md)). + Trailing comma on declaration site is automatically disabled if the [Wrapping](#wrapping) rule (or, before version `0.45.0`, the [Indentation](#indentation) rule) is disabled or not loaded. Because it cannot provide proper formatting with unwrapped declarations. (see [dependencies](./dependencies.md)). + + === "[:material-heart:](#) Trailing comma with wrapping" + + ```kotlin + class FooWrapper( + val foo = Foo( + a = 3, + b = 4, + ), + ) + ``` + === "[:material-heart-off-outline:](#) Trailing comma without wrapping" + + ```kotlin + class FooWrapper(val foo = Foo( + a = 3, + b = 4, + ),) // it's weird to insert "," between unwrapped (continued) parenthesis + ``` + Rule id: `trailing-comma-on-declaration-site` From b4a54877964f19a9fbc6a7dd32812e5a538f3d50 Mon Sep 17 00:00:00 2001 From: paul-dingemans Date: Tue, 31 Jan 2023 20:52:53 +0100 Subject: [PATCH 5/5] Revert change of name of code tabs --- docs/rules/standard.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/rules/standard.md b/docs/rules/standard.md index f1a608986c..deb5b92b73 100644 --- a/docs/rules/standard.md +++ b/docs/rules/standard.md @@ -187,7 +187,7 @@ Consistent removal (default) or adding of trailing comma's on call site. !!! note Trailing comma on call site is automatically disabled if the [Wrapping](#wrapping) rule (or, before version `0.45.0`, the [Indentation](#indentation) rule) is disabled or not loaded. Because it cannot provide proper formatting with unwrapped calls. (see [dependencies](./dependencies.md)). - === "[:material-heart:](#) Trailing comma with wrapping" + === "[:material-heart:](#) Ktlint" ```kotlin FooWrapper( @@ -197,7 +197,7 @@ Consistent removal (default) or adding of trailing comma's on call site. ), ) ``` - === "[:material-heart-off-outline:](#) Trailing comma without wrapping" + === "[:material-heart-off-outline:](#) Disallowed" ```kotlin FooWrapper(Foo( @@ -228,7 +228,7 @@ Consistent removal (default) or adding of trailing comma's on declaration site. !!! note Trailing comma on declaration site is automatically disabled if the [Wrapping](#wrapping) rule (or, before version `0.45.0`, the [Indentation](#indentation) rule) is disabled or not loaded. Because it cannot provide proper formatting with unwrapped declarations. (see [dependencies](./dependencies.md)). - === "[:material-heart:](#) Trailing comma with wrapping" + === "[:material-heart:](#) Ktlint" ```kotlin class FooWrapper( @@ -238,7 +238,7 @@ Consistent removal (default) or adding of trailing comma's on declaration site. ), ) ``` - === "[:material-heart-off-outline:](#) Trailing comma without wrapping" + === "[:material-heart-off-outline:](#) Disallowed" ```kotlin class FooWrapper(val foo = Foo(