Improve violation message in discouraged-comment-location

Closes #2292

CHANGELOG.md

@@ -18,6 +18,7 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 * Do not force blank line before function in right hand side of assignment `blank-line-before-declaration` [#2260](https://github.com/pinterest/ktlint/issue/2260)
 * Ignore override of function in rule `function-naming` [#2271](https://github.com/pinterest/ktlint/issue/2271)
 * Do not replace function body having a return statement only in case the return statement contains an intermediate exit point 'function-expression-body' [#2269](https://github.com/pinterest/ktlint/issue/2269)
+* Improve violation message in `discouraged-comment-location` [#2292](https://github.com/pinterest/ktlint/issue/2292)
 
 ### Changed
 

ktlint-ruleset-standard/src/main/kotlin/com/pinterest/ktlint/ruleset/standard/rules/DiscouragedCommentLocationRule.kt

@@ -112,7 +112,8 @@ public class DiscouragedCommentLocationRule : StandardRule("discouraged-comment-
                 // of that type. However, if it would be possible, it is ok to emit the error analog to the VALUE_ARGUMENT
                 emit(
                     node.startOffset,
-                    "A comment in a '${node.treeParentElementTypeName()}' is only allowed when placed on a new line before this element",
+                    "A (block or EOL) comment inside or on same line after a '${node.treeParentElementTypeName()}' is not allowed. It " +
+                        "may be placed on a separate line above.",
                     false,
                 )
             }

ktlint-ruleset-standard/src/test/kotlin/com/pinterest/ktlint/ruleset/standard/rules/DiscouragedCommentLocationRuleTest.kt

@@ -501,15 +501,21 @@ class DiscouragedCommentLocationRuleTest {
                 """
                 class Foo1(
                     // some comment
-                    val bar: Bar
+                    val bar: Bar,
+                    // some comment
+                    val bar: Bar,
                 )
                 class Foo2(
                     /* some comment */
-                    val bar: Bar
+                    val bar: Bar,
+                    /* some comment */
+                    val bar: Bar,
                 )
                 class Foo3(
                     /** some comment */
-                    val bar: Bar
+                    val bar: Bar,
+                    /** some comment */
+                    val bar: Bar,
                 )
                 """.trimIndent()
             discouragedCommentLocationRuleAssertThat(code).hasNoLintViolations()
@@ -534,8 +540,8 @@ class DiscouragedCommentLocationRuleTest {
             @Suppress("ktlint:standard:parameter-list-wrapping", "ktlint:standard:max-line-length")
             discouragedCommentLocationRuleAssertThat(code)
                 .hasLintViolationsWithoutAutoCorrect(
-                    LintViolation(3, 9, "A comment in a 'value_parameter' is only allowed when placed on a new line before this element"),
-                    LintViolation(7, 14, "A comment in a 'value_parameter' is only allowed when placed on a new line before this element"),
+                    LintViolation(3, 9, "A (block or EOL) comment inside or on same line after a 'value_parameter' is not allowed. It may be placed on a separate line above."),
+                    LintViolation(7, 14, "A (block or EOL) comment inside or on same line after a 'value_parameter' is not allowed. It may be placed on a separate line above."),
                     LintViolation(10, 14, "A kdoc in a 'value_parameter' is only allowed when placed on a new line before this element"),
                 )
         }
@@ -557,9 +563,9 @@ class DiscouragedCommentLocationRuleTest {
             @Suppress("ktlint:standard:parameter-list-wrapping", "ktlint:standard:max-line-length")
             discouragedCommentLocationRuleAssertThat(code)
                 .hasLintViolationsWithoutAutoCorrect(
-                    LintViolation(2, 18, "A comment in a 'value_parameter' is only allowed when placed on a new line before this element"),
-                    LintViolation(5, 18, "A comment in a 'value_parameter' is only allowed when placed on a new line before this element"),
-                    LintViolation(8, 18, "A comment in a 'value_parameter' is only allowed when placed on a new line before this element"),
+                    LintViolation(2, 18, "A (block or EOL) comment inside or on same line after a 'value_parameter' is not allowed. It may be placed on a separate line above."),
+                    LintViolation(5, 18, "A (block or EOL) comment inside or on same line after a 'value_parameter' is not allowed. It may be placed on a separate line above."),
+                    LintViolation(8, 18, "A (block or EOL) comment inside or on same line after a 'value_parameter' is not allowed. It may be placed on a separate line above."),
                 )
         }
 
@@ -820,4 +826,31 @@ class DiscouragedCommentLocationRuleTest {
                 )
         }
     }
+
+    @Test
+    fun `Given value argument preceded by a KDOC plus an EOL or BLOCK comments on separate lines above`() {
+        val code =
+            """
+            class Foo(
+                /** Some kdoc */
+                /* Some comment */
+                val bar1: Int,
+                /** Some kdoc */
+                // Some comment
+                val bar2: Int,
+                /* Some comment */
+                /** Some kdoc */
+                val bar3: Int,
+                // Some comment
+                /** Some kdoc */
+                val bar4: Int,
+            )
+            """.trimIndent()
+        @Suppress("ktlint:standard:parameter-list-wrapping", "ktlint:standard:max-line-length")
+        discouragedCommentLocationRuleAssertThat(code)
+            .hasLintViolationsWithoutAutoCorrect(
+                LintViolation(3, 5, "A (block or EOL) comment inside or on same line after a 'value_parameter' is not allowed. It may be placed on a separate line above."),
+                LintViolation(6, 5, "A (block or EOL) comment inside or on same line after a 'value_parameter' is not allowed. It may be placed on a separate line above."),
+            )
+    }
 }