diff --git a/docs/rules/standard.md b/docs/rules/standard.md index ce4acda8db..deb5b92b73 100644 --- a/docs/rules/standard.md +++ b/docs/rules/standard.md @@ -178,12 +178,35 @@ 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 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:](#) Ktlint" + + ```kotlin + FooWrapper( + Foo( + a = 3, + b = 4, + ), + ) + ``` + === "[:material-heart-off-outline:](#) Disallowed" + + ```kotlin + FooWrapper(Foo( + a = 3, + b = 4, + ),) // it's weird to insert "," between unwrapped (continued) parenthesis + ``` + + Rule id: `trailing-comma-on-call-site` ## Trailing comma on declaration site @@ -191,17 +214,40 @@ 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: + 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 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:](#) Ktlint" + + ```kotlin + class FooWrapper( + val foo = Foo( + a = 3, + b = 4, + ), + ) + ``` + === "[:material-heart-off-outline:](#) Disallowed" + + ```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` ## Wrapping