Documentation unclear/inconsistent about rule names

[Crell]

Expected Behavior

On the rules list documentation page (https://pinterest.github.io/ktlint/latest/rules/standard), there is a great deal of inconsistency in how rules are named. For example, trailing commas.

https://pinterest.github.io/ktlint/latest/rules/standard/#trailing-comma-on-call-site

The "configuration settings" block defines it as ij_kotlin_allow_trailing_comma_on_call_site. The "rule id" is standard:trailing-comma-on-call-site. The "suppress or disable" popup calls it ktlint_standard_trailing-comma-on-call-site.

It is not at all obvious which one is correct; I didn't even notice the difference until someone in Slack pointed it out to me. Experimentally, I've found that only the first one actually works when I put it in my .editorconfig. The others give a warning in my IDE that the property is not defined, which I assumed was simply because they are not part of the .editorconfig spec.

Also, the "suppress or disable" popup says to use = enabled, while the actual rule that works requires = true.

Because my IDE is rejecting ktlint_code_style as well, I'm not clear if that is actually being applied. There's no lj_kotlin_ version of it, and that version is also marked as not-recognized in the editor.

Observed Behavior

I expect the docs to be consistent and accurate, not confusing. I was instead confused.

Steps to Reproduce

See the docs page linked above.

Your Environment

# ./gradlew ktlintFormat --version

------------------------------------------------------------
Gradle 8.8
------------------------------------------------------------

Build time:   2024-05-31 21:46:56 UTC
Revision:     4bd1b3d3fc3f31db5a26eecb416a165b8cc36082

Kotlin:       1.9.22
Groovy:       3.0.21
Ant:          Apache Ant(TM) version 1.10.13 compiled on January 4 2023
JVM:          21.0.3 (Amazon.com Inc. 21.0.3+9-LTS)
OS:           Mac OS X 14.5 aarch64

ktlint version: 12.1.1

[paul-dingemans]

It is not at all obvious which one is correct; I didn't even notice the difference until someone in Slack pointed it out to me. Experimentally, I've found that only the first one actually works when I put it in my .editorconfig. The others give a warning in my IDE that the property is not defined, which I assumed was simply because they are not part of the .editorconfig spec.

The naming standard used, differs per purpose. It is indeed not fully consistent due to (historical) limitations.

Also, the "suppress or disable" popup says to use = enabled, while the actual rule that works requires = true.

The correct usage is enabled and disabled. Value true and false to disable a rule are not recognized by ktlint. Does your .editorconfig contains a glob like [*.{kt,kts}]? See https://pinterest.github.io/ktlint/latest/rules/configuration-ktlint/

The .editorconfig plugin in Intellij IDEA indeed does not recognize the ktlint properties. But no worries, ktlint does recognize them. See https://youtrack.jetbrains.com/issue/IJPL-30188/EditorConfig-inspections-marks-ktlint-properties-with-The-property-is-not-supported

[Crell]

If I put any of these lines in the .editorconfig file, ktlint removes all trailing commas:

ktlint_standard_trailing-comma-on-call-site = enabled
ktlint_standard_trailing-comma-on-call-site = disabled
ij_kotlin_allow_trailing_comma_on_call_site = false

If I put this line in the file:

ij_kotlin_allow_trailing_comma_on_call_site = true

Then it adds trailing commas everywhere.

Yes, these rules are all under a [*.{kt,kts}] block.

[paul-dingemans]

I see.

The ktlint configuration settings (prefixed with ktlint) are set with enabled or disabled. When ktlint_standard_trailing-comma-on-call-site is enabled the ktlint rule uses the Intellij IDEA setting ij_kotlin_allow_trailing_comma_on_call_site to add/remove the trailing comma. The ij_kotlin_allow_trailing_comma_on_call_site is indeed set with value true or false.

When ktlint_standard_trailing-comma-on-call-site ktlint will not run the rule. Note that Intellij IDEA formatting will still apply based on setting ij_kotlin_allow_trailing_comma_on_call_site.

I hope this makes it more clear. If you have suggestions for improving the docs, please raise a PR.