addKdoc not working as expected when property is involved

[PhilippNowak96]

Describe the bug

When having a data class with primary constructor parameters and corresponding property specs, adding a KDoc to the parameter adds it to the property doc itself instead of the class doc.

To Reproduce

I took some of the example from #843. Here is a failing unit test for my case:

@Test
fun kdocTest() {
    val taco = TypeSpec.classBuilder("Taco")
        .addModifiers(KModifier.DATA)
        .addKdoc("Some class description")
        .primaryConstructor(
            FunSpec.constructorBuilder()
                .addParameter(
                    ParameterSpec.builder("mild", Boolean::class)
                        .addKdoc("Whether the taco is mild (ew) or crunchy (ye).")
                        .build()
                )
                .build()
        )
        .addProperty(
            PropertySpec.builder("mild", Boolean::class)
                .initializer("mild")
                .build()
        )
        .build()

    val expected = """
    |/**
    | * Some class description
    | *
    | * @param mild Whether the taco is mild (ew) or crunchy (ye).
    | */
    |public data class Taco(
    |  public val mild: kotlin.Boolean,
    |)
    |""".trimMargin()

    assertEquals(expected, taco.toString())
}

Expected behavior

/**
 * Some class description
 *
 * @param mild Whether the taco is mild (ew) or crunchy (ye).
 */
public data class Taco(
  public val mild: kotlin.Boolean,
)

Actual output

/**
 * Some class description
 */
public data class Taco(
  /**
   * Whether the taco is mild (ew) or crunchy (ye).
   */
  public val mild: kotlin.Boolean,
)

---

Additional context

We managed to find a workaround. If you add the same KDoc to the PropertySpec and add something like a single whitespace at the end of the KDoc for the ParameterSpec it's kinda working. So something like

val taco = TypeSpec.classBuilder("Taco")
    .addModifiers(KModifier.DATA)
    .addKdoc("Some class description")
    .primaryConstructor(
        FunSpec.constructorBuilder()
            .addParameter(
                ParameterSpec.builder("mild", Boolean::class)
                    .addKdoc("Whether the taco is mild (ew) or crunchy (ye). ")
                    .build()
            )
            .build()
    )
    .addProperty(
        PropertySpec.builder("mild", Boolean::class)
            .addKdoc("Whether the taco is mild (ew) or crunchy (ye).")
            .initializer("mild")
            .build()
    )
    .build()

puts out the following code:

/**
 * Some class description
 *
 * @param mild Whether the taco is mild (ew) or crunchy (ye). 
 */
public data class Taco(
  /**
   * Whether the taco is mild (ew) or crunchy (ye).
   */
  public val mild: kotlin.Boolean,
)

but it would be nice if it just works the way that adding KDoc to the ParameterSpec adds it to the class documentation and adding it to the PropertySpec adds it to the property.

If we are doing something wrong, please let me know.

[Egorand]

Currently this is by design, see the following comment:

kotlinpoet/kotlinpoet/src/commonMain/kotlin/com/squareup/kotlinpoet/TypeSpec.kt

Lines 374 to 381 in 3458c5d

	/**
	* Returns KDoc comments including those of the primary constructor and its parameters.
	*
	* If the primary constructor parameter is not mapped to a property, or if the property doesn't
	* have its own KDoc - the parameter's KDoc will be attached to the parameter. Otherwise, if both
	* the parameter and the property have KDoc - the property's KDoc will be attached to the
	* property/parameter, and the parameter's KDoc will be printed in the type header.
	*/

That said, I think it makes sense to always render parameter docs in the class header: if they're attached to the parameter itself, pressing F1 on the class name or on the constructor keyword does not show the docs, as it would when the doc is part of the class header.

[PhilippNowak96]

Thank you very much for the fast change! :)