KT-50292 - Implement vertical alignment of parameters (#2309)

* Implement vertical alignment (wrapping) of parameters for kt

* Add tests for params wrapping and extend matchers to check for classes

* Add distinguishable parameters block to kotlinAsJava, extract common logic

* Create a separate Kind for symbol function parameters

3 files changed, 78 insertions, 24 deletions

diff --git a/plugins/kotlin-as-java/api/kotlin-as-java.api b/plugins/kotlin-as-java/api/kotlin-as-java.api
index 4dd8b33a..f941582e 100644
--- a/plugins/kotlin-as-java/api/kotlin-as-java.api
+++ b/plugins/kotlin-as-java/api/kotlin-as-java.api
@@ -19,6 +19,7 @@ public final class org/jetbrains/dokka/kotlinAsJava/signatures/JavaSignatureProv
 	public fun annotationsInline (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/model/AnnotationTarget;)V
 	public fun annotationsInlineWithIgnored (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/model/AnnotationTarget;Ljava/util/Set;Lorg/jetbrains/dokka/base/signatures/AtStrategy;Lkotlin/Pair;Ljava/lang/String;)V
 	public fun modifiers (Lorg/jetbrains/dokka/model/properties/WithExtraProperties;)Ljava/util/Map;
+	public fun parametersBlock (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/model/DFunction;Lkotlin/jvm/functions/Function2;)V
 	public fun plus (Ljava/util/Map;Ljava/util/Map;)Ljava/util/Map;
 	public fun signature (Lorg/jetbrains/dokka/model/Documentable;)Ljava/util/List;
 	public fun stylesIfDeprecated (Lorg/jetbrains/dokka/model/properties/WithExtraProperties;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;)Ljava/util/Set;
@@ -36,6 +37,7 @@ public final class org/jetbrains/dokka/kotlinAsJava/signatures/JavaSignatureUtil
 	public fun annotationsInline (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/model/AnnotationTarget;)V
 	public fun annotationsInlineWithIgnored (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/model/AnnotationTarget;Ljava/util/Set;Lorg/jetbrains/dokka/base/signatures/AtStrategy;Lkotlin/Pair;Ljava/lang/String;)V
 	public fun modifiers (Lorg/jetbrains/dokka/model/properties/WithExtraProperties;)Ljava/util/Map;
+	public fun parametersBlock (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/model/DFunction;Lkotlin/jvm/functions/Function2;)V
 	public fun plus (Ljava/util/Map;Ljava/util/Map;)Ljava/util/Map;
 	public fun stylesIfDeprecated (Lorg/jetbrains/dokka/model/properties/WithExtraProperties;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;)Ljava/util/Set;
 	public fun toSignatureString (Ljava/util/Collection;)Ljava/lang/String;
diff --git a/plugins/kotlin-as-java/src/main/kotlin/signatures/JavaSignatureProvider.kt b/plugins/kotlin-as-java/src/main/kotlin/signatures/JavaSignatureProvider.kt
index 65b34017..fa1f668f 100644
--- a/plugins/kotlin-as-java/src/main/kotlin/signatures/JavaSignatureProvider.kt
+++ b/plugins/kotlin-as-java/src/main/kotlin/signatures/JavaSignatureProvider.kt
@@ -8,10 +8,7 @@ import org.jetbrains.dokka.base.translators.documentables.PageContentBuilder
 import org.jetbrains.dokka.links.DRI
 import org.jetbrains.dokka.model.*
 import org.jetbrains.dokka.model.properties.WithExtraProperties
-import org.jetbrains.dokka.pages.ContentKind
-import org.jetbrains.dokka.pages.ContentNode
-import org.jetbrains.dokka.pages.TextStyle
-import org.jetbrains.dokka.pages.TokenStyle
+import org.jetbrains.dokka.pages.*
 import org.jetbrains.dokka.plugability.DokkaContext
 import org.jetbrains.dokka.plugability.plugin
 import org.jetbrains.dokka.plugability.querySingle
@@ -143,12 +140,14 @@ class JavaSignatureProvider internal constructor(ctcc: CommentsToContentConverte
                     +buildSignature(it)
                 }
                 punctuation("(")
-                list(f.parameters, separatorStyles = mainStyles + TokenStyle.Punctuation) {
-                    annotationsInline(it)
-                    text(it.modifiers()[sourceSet]?.toSignatureString() ?: "", styles = mainStyles + TokenStyle.Keyword)
-                    signatureForProjection(it.type)
-                    text(nbsp.toString())
-                    text(it.name!!)
+                if (f.parameters.isNotEmpty()) {
+                    parametersBlock(f) {
+                        annotationsInline(it)
+                        text(it.modifiers()[sourceSet]?.toSignatureString() ?: "", styles = mainStyles + TokenStyle.Keyword)
+                        signatureForProjection(it.type)
+                        text(nbsp.toString())
+                        text(it.name!!)
+                    }
                 }
                 punctuation(")")
             }
diff --git a/plugins/kotlin-as-java/src/test/kotlin/KotlinAsJavaPluginTest.kt b/plugins/kotlin-as-java/src/test/kotlin/KotlinAsJavaPluginTest.kt
index 5fcb22aa..b9627f9b 100644
--- a/plugins/kotlin-as-java/src/test/kotlin/KotlinAsJavaPluginTest.kt
+++ b/plugins/kotlin-as-java/src/test/kotlin/KotlinAsJavaPluginTest.kt
@@ -1,20 +1,19 @@
 package kotlinAsJavaPlugin
 
-import org.jetbrains.dokka.model.dfs
-import org.jetbrains.dokka.pages.*
-import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
-import org.jetbrains.kotlin.utils.addToStdlib.cast
-import org.junit.jupiter.api.Test
 import matchers.content.*
 import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
 import org.jetbrains.dokka.jdk
+import org.jetbrains.dokka.model.dfs
+import org.jetbrains.dokka.pages.*
+import org.jetbrains.kotlin.utils.addToStdlib.cast
 import org.junit.Assert
+import org.junit.jupiter.api.Test
+import signatures.Parameter
+import signatures.Parameters
 import signatures.renderedContent
 import signatures.signature
-import utils.A
-import utils.Span
-import utils.TestOutputWriterPlugin
-import utils.match
+import utils.*
 import kotlin.test.assertEquals
 
 class KotlinAsJavaPluginTest : BaseAbstractTest() {
@@ -331,7 +330,9 @@ class KotlinAsJavaPluginTest : BaseAbstractTest() {
         ) {
             renderingStage = { _, _ ->
                 writerPlugin.writer.renderedContent("root/kotlinAsJavaPlugin/-a-b-c/some-fun.html").signature().first().match(
-                    "final ", A("Integer"), A("someFun"), "(", A("Integer"), "xd)", Span(), ignoreSpanWithTokenStyle = true
+                    "final ", A("Integer"), A("someFun"), "(", Parameters(
+                        Parameter(A("Integer"), "xd")
+                    ), ")", Span(), ignoreSpanWithTokenStyle = true
                 )
             }
         }
@@ -368,8 +369,9 @@ class KotlinAsJavaPluginTest : BaseAbstractTest() {
         ) {
             renderingStage = { _, _ ->
                 writerPlugin.writer.renderedContent("root/kotlinAsJavaPlugin/-a-b-c/some-fun.html").signature().first().match(
-                    "final ", A("Integer"), A("someFun"), "(", A("Map"), "<", A("String"),
-                    ", ", A("Integer"), "> xd)", Span(), ignoreSpanWithTokenStyle = true
+                    "final ", A("Integer"), A("someFun"), "(", Parameters(
+                        Parameter(A("Map"), "<", A("String"), ", ", A("Integer"), "> xd"),
+                    ), ")", Span(), ignoreSpanWithTokenStyle = true
                 )
             }
         }
@@ -433,7 +435,9 @@ class KotlinAsJavaPluginTest : BaseAbstractTest() {
         ) {
             renderingStage = { _, _ ->
                 writerPlugin.writer.renderedContent("root/kotlinAsJavaPlugin/-test-kt/sample.html").signature().first().match(
-                    "final static ", A("String"), A("sample"), "(", A("Integer"), "a)", Span(), ignoreSpanWithTokenStyle = true
+                    "final static ", A("String"), A("sample"), "(", Parameters(
+                        Parameter(A("Integer"), "a"),
+                    ), ")", Span(), ignoreSpanWithTokenStyle = true
                 )
             }
         }
@@ -476,7 +480,56 @@ class KotlinAsJavaPluginTest : BaseAbstractTest() {
             }
             renderingStage = { _, _ ->
                 writerPlugin.writer.renderedContent("root/kotlinAsJavaPlugin/-test/-test.html").signature().first().match(
-                    A("Test"), A("Test"), "(", A("Integer"), "xd)", Span(), ignoreSpanWithTokenStyle = true
+                    A("Test"), A("Test"), "(", Parameters(
+                        Parameter(A("Integer"), "xd")
+                    ), ")", Span(), ignoreSpanWithTokenStyle = true
+                )
+            }
+        }
+    }
+
+    @Test
+    fun `should add wrapping and indent to parameters if too many`() {
+        val writerPlugin = TestOutputWriterPlugin()
+        val configuration = dokkaConfiguration {
+            sourceSets {
+                sourceSet {
+                    sourceRoots = listOf("src/")
+                    externalDocumentationLinks = listOf(
+                        DokkaConfiguration.ExternalDocumentationLink.jdk(8),
+                        stdlibExternalDocumentationLink
+                    )
+                }
+            }
+        }
+        testInline(
+            """
+            |/src/main/kotlin/kotlinAsJavaPlugin/Wrapped.kt
+            |package kotlinAsJavaPlugin
+            |
+            |class Wrapped(val xd: Int, val l: Long, val s: String)
+        """.trimMargin(),
+            configuration,
+            pluginOverrides = listOf(writerPlugin),
+            cleanupOutput = true
+        ) {
+            pagesGenerationStage = { root ->
+                val content = root.children
+                    .flatMap { it.children<ContentPage>() }
+                    .map { it.content }.single().mainContents
+
+                val text = content.single { it is ContentHeader }.children
+                    .single() as ContentText
+
+                assertEquals("Constructors", text.text)
+            }
+            renderingStage = { _, _ ->
+                writerPlugin.writer.renderedContent("root/kotlinAsJavaPlugin/-wrapped/-wrapped.html").signature().first().match(
+                    A("Wrapped"), A("Wrapped"), "(", Parameters(
+                        Parameter(A("Integer"), "xd,").withClasses("indented"),
+                        Parameter(A("Long"), "l,").withClasses("indented"),
+                        Parameter(A("String"), "s").withClasses("indented"),
+                    ).withClasses("wrapped"), ")", Span(), ignoreSpanWithTokenStyle = true
                 )
             }
         }