I'm trying to figure out how to get ktlint 1.0.0 happy with this piece of code:

class Test(
    /** The width. */
    val width: Int,
    /** The height */
    /* XXX We should be able to figure out the height automatically. */
    val height: Int
)

Whatever I try the XXX comment triggers

discouraged-comment-location

. Any suggestions?

Have you already run lint without format? It will tell more about what exactly makes lint unhappy.

It says

A comment in a 'value_parameter' is only allowed when placed on a new line before this element (standard:discouraged-comment-location)

but I don't understand what it wants - I've tried putting blank lines in various places

Can you try to merge the kdoc and block comment into 1 kdoc? This is probably not what you want, but it might give a clue. If that doesn't work, please raise an issue.

Yeah, merging the kdoc and the block comment works.

Just had a look at your code sample. Did you notice that there were 3 violation on the same line?

src/main/kotlin/Foo.kt:5:5: A comment in a 'value_parameter' is only allowed when placed on a new line before this element (standard:discouraged-comment-location)
src/main/kotlin/Foo.kt:5:5: a block comment may not be preceded by a KDoc. Reversed order is allowed though when separated by a newline. (standard:no-consecutive-comments)
src/main/kotlin/Foo.kt:5:5: Replace the block comment with an EOL comment (standard:no-single-line-block-comment)
s

I would say that those should be descriptive enough. So, I will take no further actions on this.

I didn't see the "A block comment may not be preceded by a KDoc" messages. Do those happen in 1.0.0?

You’re right. I assumed

ktlint_official

as you did not mention anything about it. I just had another look on it. The validation message is not correct in your situation. The new message will be

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.

Still this message is not really clear in your specific example but it is the best I can come up now. There is really something weird going on in the kotlin compiler. It actually makes a difference whether the block comment is placed before or after the KDoc. When it is placed before the KDoc, it is contrary to the KDoc not a part of the value parameter. When placed after the KDoc, both the KDoc and block comment are part of the value parameter. The latter situation is difficult to handle in certain rules. Because it is really unusual to do so, this situation is just blocked by the rule so that other rules do not have to take this into account. So, in your code you can switch the order of the block comment and kdoc. It is a bit unstatisfying, but not really worth the effort to fix.