Always include parameter docs in the type header

square · Jan 10, 2024 · 1efd9e6 · 1efd9e6
1 parent faaca40
commit 1efd9e6
Show file tree

Hide file tree

Showing 3 changed files with 12 additions and 18 deletions.
diff --git a/kotlinpoet/src/commonMain/kotlin/com/squareup/kotlinpoet/ParameterSpec.kt b/kotlinpoet/src/commonMain/kotlin/com/squareup/kotlinpoet/ParameterSpec.kt
@@ -54,10 +54,8 @@ public class ParameterSpec private constructor(
   internal fun emit(
     codeWriter: CodeWriter,
     includeType: Boolean = true,
-    emitKdoc: Boolean = false,
     inlineAnnotations: Boolean = true,
   ) {
-    if (emitKdoc) codeWriter.emitKdoc(kdoc.ensureEndsWithNewLine())
     codeWriter.emitAnnotations(annotations, inlineAnnotations)
     codeWriter.emitModifiers(modifiers)
     if (name.isNotEmpty()) codeWriter.emitCode("%N", this)

diff --git a/kotlinpoet/src/commonMain/kotlin/com/squareup/kotlinpoet/TypeSpec.kt b/kotlinpoet/src/commonMain/kotlin/com/squareup/kotlinpoet/TypeSpec.kt
@@ -209,7 +209,7 @@ public class TypeSpec private constructor(
               )
               param.emitDefaultValue(codeWriter)
             } else {
-              param.emit(codeWriter, emitKdoc = true, inlineAnnotations = false)
+              param.emit(codeWriter, inlineAnnotations = false)
             }
           }
 
@@ -374,10 +374,7 @@ public class TypeSpec private constructor(
   /**
    * 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.
+   * Parameters' KDocs, if present, will always be printed in the type header.
    */
   private fun kdocWithConstructorDocs(): CodeBlock {
     val classKdoc = kdoc.ensureEndsWithNewLine()
@@ -386,10 +383,8 @@ public class TypeSpec private constructor(
         if (primaryConstructor.kdoc.isNotEmpty()) {
           add("@constructor %L", primaryConstructor.kdoc.ensureEndsWithNewLine())
         }
-        val constructorProperties = constructorProperties()
         primaryConstructor.parameters.forEach { parameter ->
-          val propertyKdoc = constructorProperties[parameter.name]?.kdoc ?: CodeBlock.EMPTY
-          if (parameter.kdoc.isNotEmpty() && propertyKdoc.isNotEmpty() && parameter.kdoc != propertyKdoc) {
+          if (parameter.kdoc.isNotEmpty()) {
             add("@param %L %L", parameter.name, parameter.kdoc.ensureEndsWithNewLine())
           }
         }

diff --git a/kotlinpoet/src/commonTest/kotlin/com/squareup/kotlinpoet/TypeSpecTest.kt b/kotlinpoet/src/commonTest/kotlin/com/squareup/kotlinpoet/TypeSpecTest.kt
@@ -1975,14 +1975,12 @@ class TypeSpecTest {
         | * [random][java.util.Random] tex-mex stuff we could find in the pantry
         | * and some [kotlin.String] cheese.
         | *
+        | * @param temperature Taco temperature. Can be as cold as the famous ice tacos from
+        | * the Andes, or hot with lava-like cheese from the depths of
+        | * the Ninth Circle.
         | * @param mild Whether the taco is mild (ew) or crunchy (ye).
         | */
         |public class Taco(
-        |  /**
-        |   * Taco temperature. Can be as cold as the famous ice tacos from
-        |   * the Andes, or hot with lava-like cheese from the depths of
-        |   * the Ninth Circle.
-        |   */
         |  temperature: Double,
         |  /**
         |   * True for a soft flour tortilla; false for a crunchy corn tortilla.
@@ -4805,6 +4803,9 @@ class TypeSpecTest {
       | * This is a thing for stuff.
       | *
       | * @constructor Construct a thing!
+      | * @param first the first thing
+      | * @param second the second thing
+      | * @param third the third thing
       | */
       |public class MyType(
       |  /**
@@ -4839,10 +4840,10 @@ class TypeSpecTest {
       .build()
     assertThat(typeSpec.toString()).isEqualTo(
       """
+      |/**
+      | * @param first the first thing
+      | */
       |public class MyType(
-      |  /**
-      |   * the first thing
-      |   */
       |  first: kotlin.Int,
       |)
       |