From dcec7bac7684fb9036e5ac830cd4b8aed48f745c Mon Sep 17 00:00:00 2001 From: Paul Dingemans Date: Tue, 23 Apr 2024 11:56:23 +0200 Subject: [PATCH] Improve documentation about prevent conflicts with Intellij IDEA formatting (#2642) Closes #2639 --- .../docs/rules/configuration-intellij-idea.md | 63 ++++++++----------- .../release-latest/docs/rules/standard.md | 10 +-- .../docs/rules/configuration-intellij-idea.md | 63 ++++++++----------- documentation/snapshot/docs/rules/standard.md | 12 ++-- 4 files changed, 61 insertions(+), 87 deletions(-) diff --git a/documentation/release-latest/docs/rules/configuration-intellij-idea.md b/documentation/release-latest/docs/rules/configuration-intellij-idea.md index a7c570cfa4..d465d63584 100644 --- a/documentation/release-latest/docs/rules/configuration-intellij-idea.md +++ b/documentation/release-latest/docs/rules/configuration-intellij-idea.md @@ -1,36 +1,27 @@ -!!! Warning - `ktlint` strives to prevent code formatting conflicts with IntelliJ IDEA / Android Studio. We recommend using either IDE formatting or `ktlint` formatting. However, if you persist on using both, then please ensure that the formatting settings are aligned as described below. This reduces the chance that code which is formatted by ktlint conflicts with formatting by the IntelliJ IDEA built-in formatter. - -!!! Note - IntelliJ IDEA supports the [kotlin coding conventions](https://kotlinlang.org/docs/coding-conventions.html). As of version 0.47.x of ktlint, the support to overwrite some configuration files of IntelliJ IDEA has been dropped as it no longer fits the scope of the project. - - -Steps: - -1. Go to your project directory -2. Create or replace file `.idea/codeStyles/codeStyleConfig.xml` with content below: - ```xml - - - - - ``` -3. Create or replace file `.idea/codeStyles/Project.xml` with content below: - ```xml - - - - - - - - - - ``` +# Intellij IDEA configuration + +`ktlint` strives to prevent code formatting conflicts with IntelliJ IDEA / Android Studio as much as possible. In some cases, `ktlint` deliberately deviates from IDEA formatting. + +## Preventing conflicts + +Many conflicts can be prevented by setting following `.editorconfig` settings: +``` +root = true + +[*] +insert_final_newline = true + +[{*.kt,*.kts}] +ij_kotlin_code_style_defaults = KOTLIN_OFFICIAL + +# Disable wildcard imports entirely +ij_kotlin_name_count_to_use_star_import = 2147483647 +ij_kotlin_name_count_to_use_star_import_for_members = 2147483647 +ij_kotlin_packages_to_use_import_on_demand = unset +``` + +Conflicts between `ktlint` and IDEA formatting can also be resolved by using the [ktlint-intellij-plugin](https://plugins.jetbrains.com/plugin/15057-ktlint) (or install via Intellij IDEA plugin marketplace) in `distract free` mode. In this mode, the plugin formats your code with `ktlint` while you're editing the code. + +# Cleaning up old XML configuration settings + +Projects which have been created with (old)er versions of Intellij IDEA might still contain XML configuration regarding code styling. It is advised to remove the directory `.idea/codeStyles` whenever it still exists in your project directory. diff --git a/documentation/release-latest/docs/rules/standard.md b/documentation/release-latest/docs/rules/standard.md index df569ff720..6a7c9853f2 100644 --- a/documentation/release-latest/docs/rules/standard.md +++ b/documentation/release-latest/docs/rules/standard.md @@ -1282,15 +1282,11 @@ No wildcard imports except whitelisted imports. ``` | Configuration setting | ktlint_official | intellij_idea | android_studio | -|:------------------------------------------------------------------------------------------|:---------------:|:------------------------------------------:|:-----------------------------------------------:| -| `ij_kotlin_packages_to_use_import_on_demand`
Defines allowed wildcard imports. | - | `java.util.*,`
`kotlinx.android.synthetic.**` | `java.util.*,`
`kotlinx.android.synthetic.**` | +|:--------------------------------------------------------------------------------------------------------------------|:---------------:|:------------------------------------------:|:-----------------------------------------------:| +| `ij_kotlin_packages_to_use_import_on_demand`
Defines allowed wildcard imports as a comma separated list. | - | `java.util.*,`
`kotlinx.android.synthetic.**` | `java.util.*,`
`kotlinx.android.synthetic.**` | !!! warning - In case property `ij_kotlin_packages_to_use_import_on_demand` is not explicitly set, it allows wildcards imports like `java.util.*` by default to keep in sync with IntelliJ IDEA behavior. To disallow *all* wildcard imports, add property below to your `.editorconfig`: - ```editorconfig - [*.{kt,kts}] - ij_kotlin_packages_to_use_import_on_demand = unset - ``` + In case property `ij_kotlin_packages_to_use_import_on_demand` is not explicitly set, Intellij IDEA allows wildcards imports like `java.util.*` which lead to conflicts with the `no-wildcard-imports` rule. See [Intellij IDEA configuration](configuration-intellij-idea.md) to prevent such conflicts. Configuration setting `ij_kotlin_packages_to_use_import_on_demand` is a comma separated string of import paths. This can be a full path, e.g. "java.util.List.*", or a wildcard path, e.g. "kotlin.**". Use "**" as wildcard for package and all subpackages. diff --git a/documentation/snapshot/docs/rules/configuration-intellij-idea.md b/documentation/snapshot/docs/rules/configuration-intellij-idea.md index a7c570cfa4..e877b5592b 100644 --- a/documentation/snapshot/docs/rules/configuration-intellij-idea.md +++ b/documentation/snapshot/docs/rules/configuration-intellij-idea.md @@ -1,36 +1,27 @@ -!!! Warning - `ktlint` strives to prevent code formatting conflicts with IntelliJ IDEA / Android Studio. We recommend using either IDE formatting or `ktlint` formatting. However, if you persist on using both, then please ensure that the formatting settings are aligned as described below. This reduces the chance that code which is formatted by ktlint conflicts with formatting by the IntelliJ IDEA built-in formatter. - -!!! Note - IntelliJ IDEA supports the [kotlin coding conventions](https://kotlinlang.org/docs/coding-conventions.html). As of version 0.47.x of ktlint, the support to overwrite some configuration files of IntelliJ IDEA has been dropped as it no longer fits the scope of the project. - - -Steps: - -1. Go to your project directory -2. Create or replace file `.idea/codeStyles/codeStyleConfig.xml` with content below: - ```xml - - - - - ``` -3. Create or replace file `.idea/codeStyles/Project.xml` with content below: - ```xml - - - - - - - - - - ``` +# Intellij IDEA configuration + +`ktlint` strives to prevent code formatting conflicts with IntelliJ IDEA / Android Studio as much as possible. In some cases, `ktlint` deliberately deviates from IDEA formatting. + +## Preventing conflicts + +Many conflicts can be prevented by setting following `.editorconfig` settings: +``` +root = true + +[*] +insert_final_newline = true + +[{*.kt,*.kts}] +ij_kotlin_code_style_defaults = KOTLIN_OFFICIAL + +# Disable wildcard imports entirely +ij_kotlin_name_count_to_use_star_import = 2147483647 +ij_kotlin_name_count_to_use_star_import_for_members = 2147483647 +ij_kotlin_packages_to_use_import_on_demand = unset +``` + +Conflicts between `ktlint` and IDEA formatting can also be resolved by using the [ktlint-intellij-plugin](https://plugins.jetbrains.com/plugin/15057-ktlint) (or install via Intellij IDEA plugin marketplace) in `distract free` mode. In this mode, the plugin formats your code with `ktlint` while you're editing the code. + +# Cleaning up old XML configuration settings + +Projects which have been created with (old)er versions of Intellij IDEA might still contain XML configuration regarding code styling. It is advised to remove the directory `.idea/codeStyles` whenever it still exists in your project directory. diff --git a/documentation/snapshot/docs/rules/standard.md b/documentation/snapshot/docs/rules/standard.md index 05281e1af0..ad913e1a4e 100644 --- a/documentation/snapshot/docs/rules/standard.md +++ b/documentation/snapshot/docs/rules/standard.md @@ -1281,16 +1281,12 @@ No wildcard imports except whitelisted imports. import foobar.* ``` -| Configuration setting | ktlint_official | intellij_idea | android_studio | -|:------------------------------------------------------------------------------------------|:---------------:|:------------------------------------------:|:-----------------------------------------------:| -| `ij_kotlin_packages_to_use_import_on_demand`
Defines allowed wildcard imports. | - | `java.util.*,`
`kotlinx.android.synthetic.**` | `java.util.*,`
`kotlinx.android.synthetic.**` | +| Configuration setting | ktlint_official | intellij_idea | android_studio | +|:--------------------------------------------------------------------------------------------------------------------|:---------------:|:------------------------------------------:|:-----------------------------------------------:| +| `ij_kotlin_packages_to_use_import_on_demand`
Defines allowed wildcard imports as a comma separated list. | - | `java.util.*,`
`kotlinx.android.synthetic.**` | `java.util.*,`
`kotlinx.android.synthetic.**` | !!! warning - In case property `ij_kotlin_packages_to_use_import_on_demand` is not explicitly set, it allows wildcards imports like `java.util.*` by default to keep in sync with IntelliJ IDEA behavior. To disallow *all* wildcard imports, add property below to your `.editorconfig`: - ```editorconfig - [*.{kt,kts}] - ij_kotlin_packages_to_use_import_on_demand = unset - ``` + In case property `ij_kotlin_packages_to_use_import_on_demand` is not explicitly set, Intellij IDEA allows wildcards imports like `java.util.*` which lead to conflicts with the `no-wildcard-imports` rule. See [Intellij IDEA configuration](configuration-intellij-idea.md) to prevent such conflicts. Configuration setting `ij_kotlin_packages_to_use_import_on_demand` is a comma separated string of import paths. This can be a full path, e.g. "java.util.List.*", or a wildcard path, e.g. "kotlin.**". Use "**" as wildcard for package and all subpackages.