Skip to content

Commit

Permalink
Move configuration setting documentation to rule (#2489)
Browse files Browse the repository at this point in the history 
For settings which are tied to a specific rule, it is more clear to have the setting documented at the same place as the rule. Other generic settings are kept at the configuration page.
  • Loading branch information
@paul-dingemans
paul-dingemans committed Jan 5, 2024
1 parent bc4b180 commit f5fbd36
Show file tree
Hide file tree
Showing 8 changed files with 360 additions and 512 deletions.
239 changes: 22 additions & 217 deletions documentation/release-latest/docs/rules/configuration-ktlint.md
View file
Expand Up @@ -13,7 +13,7 @@ By default, the `ktlint_official` code style is applied. Alternatively, the code
ktlint_code_style = ktlint_official
```

## Disabled rules
## Disable rule(s)

Rule sets and individual rules can be disabled / enabled with a separate property per rule (set).

Expand All @@ -39,221 +39,26 @@ ktlint_custom-rule-set_custom-rule = disabled # Disables the `custom-rule` rule
!!! note
The *rule* properties are applied after applying the *rule set* properties and take precedence. So if a rule set is disabled but a specific rule of that rule set is enabled, then the rule will be executed.


## Final newline

By default, a final newline is required at the end of the file.

```ini
[*.{kt,kts}]
insert_final_newline = true
```

This setting only takes effect when rule `final-newline` is enabled.

## Force multiline chained methods based on number of chain operators

Setting `ktlint_chain_method_rule_force_multiline_when_chain_operator_count_greater_or_equal_than` forces a chained method to be wrapped at each chain operator (`.` or `?.`) in case it contains the specified minimum number of chain operators even in case the entire chained method fits on a single line. Use value `unset` (default) to disable this setting.

!!! note
By default, chained methods are wrapped when an expression contains 4 or more chain operators in an expression. Note that if a chained method contains nested expressions the chain operators of the inner expression are not taken into account.

```ini
[*.{kt,kts}]
ktlint_chain_method_rule_force_multiline_when_chain_operator_count_greater_or_equal_than=unset
```

This setting only takes effect when rule `chain-method-continution` is enabled.

## Force multiline function signature based on number of parameters

Setting `ktlint_function_signature_rule_force_multiline_when_parameter_count_greater_or_equal_than` forces a multiline function signature in case the function contains the specified minimum number of parameters even in case the function signature would fit on a single line. Use value `unset` (default) to disable this setting.

!!! note
By default, the `ktlint_official` code style wraps parameters of functions having at least 2 parameters. For other code styles, this setting is disabled by default.

```ini
[*.{kt,kts}]
ktlint_function_signature_rule_force_multiline_when_parameter_count_greater_or_equal_than=unset
```

This setting only takes effect when rule `function-signature` is enabled.

## Wrapping the expression body of a function

Setting `ktlint_function_signature_body_expression_wrapping` determines if and when the expression body of a function is wrapped to a new line. This setting can be set to value `default`, `multiline` or `always`.

!!! note
In this context `default` means the default behavior of the IntelliJ IDEA formatter. If not set explicitly, this style is used by code styles `intellij_idea` and `android_studio`. Code style `ktlint_official` uses style `multiline` when this setting has no value.

When set to `default`, the first line of a body expression is appended to the function signature as long as the max line length is not exceeded.

```kotlin title="ktlint_function_signature_body_expression_wrapping=default"
// Given that the function signature has to be written as a single line function signature
fun someFunction(a: Any, b: Any): String = "some-result"
.uppercase()

// Given that the function signature has to be written as a multiline function signature
fun someFunction(
a: Any,
b: Any
): String = "some-result"
.uppercase()
```

When set to `multiline`, the body expression starts on a separate line in case it is a multiline expression. A single line body expression is wrapped only when it does not fit on the same line as the function signature.

```kotlin title="ktlint_function_signature_body_expression_wrapping=multiline"
// Given a single line body expression and
// a the function signature that has to be written as a single line function signature and
// it does not exceed the max line length
fun someFunction(a: Any, b: Any): String = "some-result".uppercase()

// Given a single line body expression and
// a the function signature that has to be written as a multiline function signature and
// it does not exceed the max line length
fun someFunction(
a: Any,
b: Any
): String = "some-result".uppercase()

// Given a single line body expression then always wrap it to a separate line
fun someFunction(a: Any, b: Any): String =
"some-result"
.uppercase()
fun someFunction(
a: Any,
b: Any
): String =
"some-result"
.uppercase()
```

When set to `always` the body expression is always wrapped to a separate line.

```kotlin title="ktlint_function_signature_body_expression_wrapping=always"
fun someFunction(a: Any, b: Any): String =
"some-result".uppercase()
fun functionWithAVeryLongName(
a: Any,
b: Any
): String =
"some-result"
.uppercase()
```

This setting only takes effect when rule `function-signature` is enabled.

## Ignore identifiers enclosed in backticks

By default, the identifiers enclosed in backticks are not ignored.

According to [Kotlin coding conventions](https://kotlinlang.org/docs/reference/coding-conventions.html#names-for-test-methods) it is acceptable to write method names in natural language. When using natural language, the description tends to be longer. This property allows lines containing an identifier between backticks to be longer than the maximum line length. (Since 0.41.0)

```kotlin
@Test
fun `Given a test with a very loooooooooooooooooooooong test description`() {

}
```

```ini
[*.{kt,kts}]
ktlint_ignore_back_ticked_identifier = false
```

This setting only takes effect when rule `max-line-length` is enabled.

## Import layouts

By default, the same imports are allowed as in IntelliJ IDEA. The import path can be a full path, e.g. "java.util.List.*" as well as wildcard path, e.g. "kotlin.**".

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
```

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.

```ini
[*.{kt,kts}]
ij_kotlin_packages_to_use_import_on_demand = java.util.*,kotlinx.android.synthetic.**
```

This setting only takes effect when rule `no-wildcard-imports` is enabled.

## Indent size & style

By default, indenting is done with 4 spaces per indent level. Code style `android_studio` uses a tab per indent level.

```ini
[*.{kt,kts}]
indent_size = 4 # possible values: number (e.g. 2), "unset" (makes ktlint ignore indentation completely)
indent_style = space # or "tab"
```

Those settings are used by multiple rules of which rule `indent` is the most important.

## Max line length

By default, the maximum line length is not set. The `android` code style sets the max line length to 100 (per Android Kotlin Style Guide).

```ini
[*.{kt,kts}]
max_line_length = off # Use "off" to ignore max line length or a positive number to set max line length
```

This setting is used by multiple rules of which rule `max-line-length` is the most important.

## Trailing comma on call site

KtLint uses the IntelliJ IDEA `.editorconfig` property `ij_kotlin_allow_trailing_comma_on_call_site` to *enforce* the usage of the trailing comma at call site when enabled. IntelliJ IDEA uses this property to *allow* the use of 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 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#trailing-commas) leaves it to the developer's discretion to use trailing commas 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.

Example:
```ini
[*.{kt,kts}]
ij_kotlin_allow_trailing_comma_on_call_site = false
```

This setting only takes effect when rule `trailing-comma-on-call-site` is enabled.

## Trailing comma on declaration site

KtLint uses the IntelliJ IDEA `.editorconfig` property `ij_kotlin_allow_trailing_comma` to *enforce* the usage of the trailing comma at declaration site when enabled. IntelliJ IDEA uses this property to *allow* the use of 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.

The [Kotlin coding conventions](https://kotlinlang.org/docs/reference/coding-conventions.html#trailing-commas) encourages the usage of trailing commas on the declaration site, but leaves it to the developer's discretion to use trailing commas 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.

Example:
```ini
[*.{kt,kts}]
ij_kotlin_allow_trailing_comma = false # Only used for declaration site
```

This setting only takes effect when rule `trailing-comma-on-declaration-site` is enabled.
## Rule specific configuration settings

The configuration settings below are used to configure the behavior of a specific rule. As of that, those settings only take effect when the corresponding rule is enabled. See description of rule for more information about the setting.

| Configuration setting | Rule |
|:------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------|
| ij_kotlin_allow_trailing_comma | [trailing-comma-on-declaration-site](../rules/standard/#trailing-comma-on-declaration-site) |
| ij_kotlin_allow_trailing_comma_on_call_site | [trailing-comma-on-call-site](../rules/standard/#trailing-comma-on-call-site) |
| ij_kotlin_packages_to_use_import_on_demand | [no-wildcard-imports](../rules/standard/#no-wildcard-imports) |
| indent_size | [indent](../rules/standard/#indentation) | |
| indent_style | [indent](../rules/standard/#indentation) | |
|
| insert_final_newline | [final-newline](../rules/standard/#final-newline) | |
| ktlint_chain_method_rule_force_multiline_when_chain_operator_count_greater_or_equal_than | [chain-method-continuation](../rules/experimental/#chain-method-continuation) |
| ktlint_class_signature_rule_force_multiline_when_parameter_count_greater_or_equal_than | [class-signature](../rules/experimental/#class-signature) |
| ktlint_ignore_back_ticked_identifier | [max-line-length](../rules/standard/#max-line-length) |
| ktlint_function_naming_ignore_when_annotated_with | [function-naming](../rules/standard/#function-naming) |
| ktlint_function_signature_body_expression_wrapping | [function-signature](../rules/standard/#function-signature) |
| ktlint_function_signature_rule_force_multiline_when_parameter_count_greater_or_equal_than | [function-signature](../rules/standard/#function-signature) |
| max_line_length | [max-line-length](../rules/standard/#max-line-length) and several other rules |

## Overriding Editorconfig properties for specific directories

Expand All @@ -266,4 +71,4 @@ ktlint_standard_import-ordering = disabled
ktlint_standard_indent = disabled
```

Note that the `import-ordering` rule is disabled for *all* packages including the `api` sub package. Next to this the `indent` rule is disabled for the `api` package and its sub packages.
Note that in example above the `import-ordering` rule is disabled for *all* packages including the `api` sub package. Next to this the `indent` rule is disabled for the `api` package and its sub packages.
9 changes: 9 additions & 0 deletions documentation/release-latest/docs/rules/experimental.md
View file
Expand Up @@ -125,6 +125,11 @@ This rule can be configured with `.editorconfig` property [`ktlint_chain_method_
.bar()
```

| Configuration setting | ktlint_official | intellij_idea | android_studio |
|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------:|:-------------:|:--------------:|
| `ktlint_chain_method_rule_force_multiline_when_chain_operator_count_greater_or_equal_than`<br/><i>Force wrapping of chained methods in case an expression contains at least the specified number of chain operators. If a chained method contains nested expressions, the chain operators of the inner expression are not taken into account. Use value `unset` (default) to disable this setting.</i> | 4 | 4 | 4 |


Rule id: `chain-method-continuation` (`standard` rule set)

!!! Note
Expand Down Expand Up @@ -331,6 +336,10 @@ The other code styles allow an infinite amount of parameters on the same line (a
class Foo6(a: Any, b: Any, c: Any) : FooBar(a, c)
```

| Configuration setting | ktlint_official | intellij_idea | android_studio |
|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------:|:-------------:|:--------------:|
| `ktlint_class_signature_rule_force_multiline_when_parameter_count_greater_or_equal_than`<br/><i>Force wrapping of the parameters of the class signature in case it contains at least the specified number of parameters, even in case the entire class signature would fit on a single line. Use value `unset` to disable this setting.</i> | 1 | `unset` | `unset` |

Rule id: `class-signature` (`standard` rule set)

## Condition wrapping
Expand Down

0 comments on commit f5fbd36

Please sign in to comment.