Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fix documentation import layouts #2869

Merged
merged 3 commits into from
Nov 17, 2024
Merged

Fix documentation import layouts #2869

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6a3507f
Fix documentation
paul-dingemans Nov 17, 2024
205e060
Fix documentation
paul-dingemans Nov 17, 2024
1af53c7
Merge remote-tracking branch 'origin/2866' into 2866
paul-dingemans Nov 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions documentation/release-latest/docs/rules/configuration-ktlint.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ The configuration settings below are used to configure the behavior of a specifi
|:------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------|
| ij_kotlin_allow_trailing_comma | [trailing-comma-on-declaration-site](../standard/#trailing-comma-on-declaration-site) |
| ij_kotlin_allow_trailing_comma_on_call_site | [trailing-comma-on-call-site](../standard/#trailing-comma-on-call-site) |
| ij_kotlin_imports_layout | [import-ordering](../standard/#import-ordering) |
| ij_kotlin_packages_to_use_import_on_demand | [no-wildcard-imports](../standard/#no-wildcard-imports) |
| indent_size | [indent](../standard/#indentation) | |
| indent_style | [indent](../standard/#indentation) | |
Expand Down
44 changes: 27 additions & 17 deletions documentation/release-latest/docs/rules/standard.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1127,7 +1127,7 @@ Suppress or disable rule (1)

## Import ordering

Ensures that imports are ordered consistently (see [Import Layouts](../configuration-ktlint/#import-layouts) for configuration).
Ensures that imports are ordered consistently.

=== "[:material-heart:](#) Ktlint"

Expand All @@ -1146,6 +1146,31 @@ Ensures that imports are ordered consistently (see [Import Layouts](../configura
import com.foo.Foo
```

| Configuration setting | ktlint_official | intellij_idea | android_studio |
|:---------------------------------------------------------------------------------------------------------------------|:----------------------------------:|:-----------------------------------:|:--------------:|
| `ij_kotlin_imports_layout`</br><i>Defines imports order layout for Kotlin files</i>For more details see below table. | *,java.**,javax.**,kotlin.**,^ <1> | *,java.**,javax.**,kotlin.**,^ <1> | * <2> |

### ij_kotlin_packages_to_use_import_on_demand

This property holds 0 or more import paths. The import path can be a full path, e.g. "java.util.List.*" as well as wildcard path, e.g. "kotlin.**".

Imports can be grouped by composing the layout with symbols below:

* `*` - wildcard. There must be at least one entry of a single wildcard to match all other imports. Matches anything after a specified symbol/import as well.
* `|` - blank line. Supports only single blank lines between imports. No blank line is allowed in the beginning or end of the layout.
* `^` - alias import, e.g. "^android.*" will match all android alias imports, "^" will match all other alias imports.

Imports in the same group are sorted alphabetical with capital letters before lower case letters (e.g. Z before a).

Examples:
```kotlin
ij_kotlin_imports_layout=* # alphabetical with capital letters before lower case letters (e.g. Z before a), no blank lines
ij_kotlin_imports_layout=*,java.**,javax.**,kotlin.**,^ # default IntelliJ IDEA style, same as alphabetical, but with "java", "javax", "kotlin" and alias imports in the end of the imports list
ij_kotlin_imports_layout=android.**,|,^org.junit.**,kotlin.io.Closeable.*,|,*,^ # custom imports layout
```

Wildcard imports can be allowed for specific import paths (Comma-separated list, use "**" as wildcard for package and all subpackages). This setting overrides the no-wildcard-imports rule. This setting is best be used for allowing wildcard imports from libraries like Ktor where extension functions are used in a way that creates a lot of imports.

Rule id: `standard:import-ordering`

Suppress or disable rule (1)
Expand Down Expand Up @@ -2548,28 +2573,13 @@ No wildcard imports except whitelisted imports.
import foobar.*
```

| Configuration setting | ktlint_official | intellij_idea | android_studio |
| Configuration setting | ktlint_official | intellij_idea | android_studio |
|:--------------------------------------------------------------------------------------------------------------------|:---------------:|:------------------------------------------:|:-----------------------------------------------:|
| `ij_kotlin_packages_to_use_import_on_demand`<br/><i>Defines allowed wildcard imports as a comma separated list.</i> | - | `java.util.*,`<br/>`kotlinx.android.synthetic.**` | `java.util.*,`<br/>`kotlinx.android.synthetic.**` |

!!! warning
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.

The layout can be composed by the following symbols:

* `*` - wildcard. There must be at least one entry of a single wildcard to match all other imports. Matches anything after a specified symbol/import as well.
* `|` - blank line. Supports only single blank lines between imports. No blank line is allowed in the beginning or end of the layout.
* `^` - alias import, e.g. "^android.*" will match all android alias imports, "^" will match all other alias imports.

Examples:
```kotlin
ij_kotlin_imports_layout=* # alphabetical with capital letters before lower case letters (e.g. Z before a), no blank lines
ij_kotlin_imports_layout=*,java.**,javax.**,kotlin.**,^ # default IntelliJ IDEA style, same as alphabetical, but with "java", "javax", "kotlin" and alias imports in the end of the imports list
ij_kotlin_imports_layout=android.**,|,^org.junit.**,kotlin.io.Closeable.*,|,*,^ # custom imports layout
```

Rule id: `standard:no-wildcard-imports`

Suppress or disable rule (1)
Expand Down
1 change: 1 addition & 0 deletions documentation/snapshot/docs/rules/configuration-ktlint.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ The configuration settings below are used to configure the behavior of a specifi
|:------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------|
| ij_kotlin_allow_trailing_comma | [trailing-comma-on-declaration-site](../standard/#trailing-comma-on-declaration-site) |
| ij_kotlin_allow_trailing_comma_on_call_site | [trailing-comma-on-call-site](../standard/#trailing-comma-on-call-site) |
| ij_kotlin_imports_layout | [import-ordering](../standard/#import-ordering) |
| ij_kotlin_packages_to_use_import_on_demand | [no-wildcard-imports](../standard/#no-wildcard-imports) |
| indent_size | [indent](../standard/#indentation) | |
| indent_style | [indent](../standard/#indentation) | |
Expand Down
44 changes: 27 additions & 17 deletions documentation/snapshot/docs/rules/standard.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1127,7 +1127,7 @@ Suppress or disable rule (1)

## Import ordering

Ensures that imports are ordered consistently (see [Import Layouts](../configuration-ktlint/#import-layouts) for configuration).
Ensures that imports are ordered consistently.

=== "[:material-heart:](#) Ktlint"

Expand All @@ -1146,6 +1146,31 @@ Ensures that imports are ordered consistently (see [Import Layouts](../configura
import com.foo.Foo
```

| Configuration setting | ktlint_official | intellij_idea | android_studio |
|:---------------------------------------------------------------------------------------------------------------------|:----------------------------------:|:-----------------------------------:|:--------------:|
| `ij_kotlin_imports_layout`</br><i>Defines imports order layout for Kotlin files</i>For more details see below table. | *,java.**,javax.**,kotlin.**,^ <1> | *,java.**,javax.**,kotlin.**,^ <1> | * <2> |

### ij_kotlin_packages_to_use_import_on_demand

This property holds 0 or more import paths. The import path can be a full path, e.g. "java.util.List.*" as well as wildcard path, e.g. "kotlin.**".

Imports can be grouped by composing the layout with symbols below:

* `*` - wildcard. There must be at least one entry of a single wildcard to match all other imports. Matches anything after a specified symbol/import as well.
* `|` - blank line. Supports only single blank lines between imports. No blank line is allowed in the beginning or end of the layout.
* `^` - alias import, e.g. "^android.*" will match all android alias imports, "^" will match all other alias imports.

Imports in the same group are sorted alphabetical with capital letters before lower case letters (e.g. Z before a).

Examples:
```kotlin
ij_kotlin_imports_layout=* # alphabetical with capital letters before lower case letters (e.g. Z before a), no blank lines
ij_kotlin_imports_layout=*,java.**,javax.**,kotlin.**,^ # default IntelliJ IDEA style, same as alphabetical, but with "java", "javax", "kotlin" and alias imports in the end of the imports list
ij_kotlin_imports_layout=android.**,|,^org.junit.**,kotlin.io.Closeable.*,|,*,^ # custom imports layout
```

Wildcard imports can be allowed for specific import paths (Comma-separated list, use "**" as wildcard for package and all subpackages). This setting overrides the no-wildcard-imports rule. This setting is best be used for allowing wildcard imports from libraries like Ktor where extension functions are used in a way that creates a lot of imports.

Rule id: `standard:import-ordering`

Suppress or disable rule (1)
Expand Down Expand Up @@ -2548,28 +2573,13 @@ No wildcard imports except whitelisted imports.
import foobar.*
```

| Configuration setting | ktlint_official | intellij_idea | android_studio |
| Configuration setting | ktlint_official | intellij_idea | android_studio |
|:--------------------------------------------------------------------------------------------------------------------|:---------------:|:------------------------------------------:|:-----------------------------------------------:|
| `ij_kotlin_packages_to_use_import_on_demand`<br/><i>Defines allowed wildcard imports as a comma separated list.</i> | - | `java.util.*,`<br/>`kotlinx.android.synthetic.**` | `java.util.*,`<br/>`kotlinx.android.synthetic.**` |

!!! warning
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.

The layout can be composed by the following symbols:

* `*` - wildcard. There must be at least one entry of a single wildcard to match all other imports. Matches anything after a specified symbol/import as well.
* `|` - blank line. Supports only single blank lines between imports. No blank line is allowed in the beginning or end of the layout.
* `^` - alias import, e.g. "^android.*" will match all android alias imports, "^" will match all other alias imports.

Examples:
```kotlin
ij_kotlin_imports_layout=* # alphabetical with capital letters before lower case letters (e.g. Z before a), no blank lines
ij_kotlin_imports_layout=*,java.**,javax.**,kotlin.**,^ # default IntelliJ IDEA style, same as alphabetical, but with "java", "javax", "kotlin" and alias imports in the end of the imports list
ij_kotlin_imports_layout=android.**,|,^org.junit.**,kotlin.io.Closeable.*,|,*,^ # custom imports layout
```

Rule id: `standard:no-wildcard-imports`

Suppress or disable rule (1)
Expand Down