KDoc comment format

[marchuk0]

Expected Rule behavior

The rule should check whether Kdoc comment conforms to one of the following rules:

1. This Kdoc is a single-line comment that starts with /** and ends with */.
2. This Kdoc is a multi-line comment and
   • Kdoc comment starts with the line /**
   • Kdoc comment ends with the line */
   • all other lines start with * except the empty lines that should look like * (with no trailing whitespace)
   • The number of leading whitespaces is the same for each line, except the first line of the Kdoc comment where the number of whitespaces is one whitespace less than other lines.

The Kotlin coding conventions or Android Style Guide do not strictly define the KDoc comment format, but examples have the same well-readable format.

1. https://kotlinlang.org/docs/kotlin-doc.html#kdoc-syntax
2. https://developer.android.com/kotlin/style-guide#formatting_2

Examples of good KDoc comments:

/**
 * A group of *members*.
 *
 * This class has no useful logic; it's just a documentation example.
 *
 * @param T the type of a member in this group.
 * @property name the name of this group.
 * @constructor Creates an empty group.
 */

/** A group of *members* */

Examples of bad Kdoc comments:

/***
 * A group of *members*.
 *
 * This class has no useful logic; it's just a documentation example.
 *
 * @param T the type of a member in this group.
 * @property name the name of this group.
 * @constructor Creates an empty group.
 */

/** A group of *members*.
 *
 * This class has no useful logic; it's just a documentation example.
 *
 * @param T the type of a member in this group.
 * @property name the name of this group.
 * @constructor Creates an empty group.
 */


/**A group of *members* */

Additional information

• Current version of ktlint: 1.5.0
• Styleguide section:

[paul-dingemans]

It could be an option to add a rule for this, and enable it by default for code style ktlint_official only. Other code styles can use the rule via opt-in.

But I do think, that the rule should only be applied whenever the indenting inside the KDoc is already correct. Code below should result in a violation message, but should not be autocorrected:

class Foo {
    /**
     * It starts well, but for some reason the lines below do not start with the star sign, and are not properly 
     * indented. Indenting them might be unwanted.
Some unindented text not starting with a star
    and more unindented text not starting with a star
     */
    fun foo() {}
}

while code below can be autocorrected

class Bar {
    /**
     * It starts well, but for some reason the lines below do not start with the star sign, and are properly indented.
     * Indenting them does not harm.
        Some indented text not starting with a star
            and more indented text not starting with a star
     */
    fun bar() {}
}

[marchuk0]

@paul-dingemans why do you think that the first example might be intended? Do you have any examples where this might be useful?

In my case, I would like to autocorrect both cases, because I want all KDoc comments to be formatted in the same obvious way. The flag to override the default behaviour suggested by you will work for me.

[paul-dingemans]

@paul-dingemans why do you think that the first example might be intended? Do you have any examples where this might be useful?

Some devs really dislike it when ktlint is altering comments or kdocs. Inside a block comment on in a KDoc nothing can be assumed about the (reason of) indentation. Also, ktlint totally ignores any comment/kdoc starting at position 0 of the line.

So in the second case, the visual indentation is not changed. It is only a single space that is replaced with an *. Even this can already be tricky in case tab-indentation is used (I think that I would discourage autocorrecting for that case as well).

For the first case, it definitely leads to altering the visiual indentation. This should be left to the developer.