From e0a10c24ea7e623137f2ab21522ed0f84bf59814 Mon Sep 17 00:00:00 2001
From: Ignat Beresnev <ignat@beresnev.me>
Date: Thu, 27 Jan 2022 12:56:27 +0300
Subject: 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
---
 core/api/core.api                          |  9 ++++++
 core/src/main/kotlin/pages/ContentNodes.kt | 45 ++++++++++++++++++++++++++++--
 2 files changed, 52 insertions(+), 2 deletions(-)

(limited to 'core')

diff --git a/core/api/core.api b/core/api/core.api
index 32d388f7..53a0ab3f 100644
--- a/core/api/core.api
+++ b/core/api/core.api
@@ -3862,10 +3862,12 @@ public final class org/jetbrains/dokka/pages/ContentResolvedLink : org/jetbrains
 public final class org/jetbrains/dokka/pages/ContentStyle : java/lang/Enum, org/jetbrains/dokka/pages/Style {
 	public static final field Caption Lorg/jetbrains/dokka/pages/ContentStyle;
 	public static final field InDocumentationAnchor Lorg/jetbrains/dokka/pages/ContentStyle;
+	public static final field Indented Lorg/jetbrains/dokka/pages/ContentStyle;
 	public static final field RowTitle Lorg/jetbrains/dokka/pages/ContentStyle;
 	public static final field RunnableSample Lorg/jetbrains/dokka/pages/ContentStyle;
 	public static final field TabbedContent Lorg/jetbrains/dokka/pages/ContentStyle;
 	public static final field WithExtraAttributes Lorg/jetbrains/dokka/pages/ContentStyle;
+	public static final field Wrapped Lorg/jetbrains/dokka/pages/ContentStyle;
 	public static fun valueOf (Ljava/lang/String;)Lorg/jetbrains/dokka/pages/ContentStyle;
 	public static fun values ()[Lorg/jetbrains/dokka/pages/ContentStyle;
 }
@@ -4197,6 +4199,13 @@ public final class org/jetbrains/dokka/pages/SimpleAttr$SimpleAttrKey : org/jetb
 public abstract interface class org/jetbrains/dokka/pages/Style {
 }
 
+public final class org/jetbrains/dokka/pages/SymbolContentKind : java/lang/Enum, org/jetbrains/dokka/pages/Kind {
+	public static final field Parameter Lorg/jetbrains/dokka/pages/SymbolContentKind;
+	public static final field Parameters Lorg/jetbrains/dokka/pages/SymbolContentKind;
+	public static fun valueOf (Ljava/lang/String;)Lorg/jetbrains/dokka/pages/SymbolContentKind;
+	public static fun values ()[Lorg/jetbrains/dokka/pages/SymbolContentKind;
+}
+
 public final class org/jetbrains/dokka/pages/TextStyle : java/lang/Enum, org/jetbrains/dokka/pages/Style {
 	public static final field Block Lorg/jetbrains/dokka/pages/TextStyle;
 	public static final field Bold Lorg/jetbrains/dokka/pages/TextStyle;
diff --git a/core/src/main/kotlin/pages/ContentNodes.kt b/core/src/main/kotlin/pages/ContentNodes.kt
index c1bb3b8c..293fe6c4 100644
--- a/core/src/main/kotlin/pages/ContentNodes.kt
+++ b/core/src/main/kotlin/pages/ContentNodes.kt
@@ -316,9 +316,25 @@ data class PlatformHintedContent(
 interface Style
 interface Kind
 
+/**
+ * [ContentKind] represents a grouping of content of one kind. This can be rendered
+ * as either a part of a composite page (one tab/block within a class's page, for instance)
+ * or as a separate page altogether.
+ */
 enum class ContentKind : Kind {
 
-    Comment, Constructors, Functions, Parameters, Properties, Classlikes, Packages, Symbol, Sample, Main, BriefComment,
+    /**
+     * Marks all sorts of signatures. Can contain sub-kinds marked as [SymbolContentKind]
+     *
+     * Some examples:
+     * - primary constructor: `data class CoroutineName(name: String) : AbstractCoroutineContextElement`
+     * - constructor: `fun CoroutineName(name: String)`
+     * - function: `open override fun toString(): String`
+     * - property: `val name: String`
+     */
+    Symbol,
+
+    Comment, Constructors, Functions, Parameters, Properties, Classlikes, Packages, Sample, Main, BriefComment,
     Empty, Source, TypeAliases, Cover, Inheritors, SourceSetDependentHint, Extensions, Annotations;
 
     companion object {
@@ -338,6 +354,30 @@ enum class ContentKind : Kind {
         fun shouldBePlatformTagged(kind: Kind): Boolean = kind in platformTagged
     }
 }
+
+/**
+ * Content kind for [ContentKind.Symbol] content, which is essentially about signatures
+ */
+enum class SymbolContentKind : Kind {
+    /**
+     * Marks constructor/function parameters, everything in-between parentheses.
+     *
+     * For function `fun foo(bar: String, baz: Int, qux: Boolean)`,
+     * the parameters would be the whole of `bar: String, baz: Int, qux: Boolean`
+     */
+    Parameters,
+
+    /**
+     * Marks a single parameter in a function. Most likely to be a child of [Parameters].
+     *
+     * In function `fun foo(bar: String, baz: Int, qux: Boolean)` there would be 3 [Parameter] instances:
+     * - `bar: String, `
+     * - `baz: Int, `
+     * - `qux: Boolean`
+     */
+    Parameter,
+}
+
 enum class TokenStyle : Style {
     Keyword, Punctuation, Function, Operator, Annotation, Number, String, Boolean, Constant, Builtin
 }
@@ -347,7 +387,8 @@ enum class TextStyle : Style {
 }
 
 enum class ContentStyle : Style {
-    RowTitle, TabbedContent, WithExtraAttributes, RunnableSample, InDocumentationAnchor, Caption
+    RowTitle, TabbedContent, WithExtraAttributes, RunnableSample, InDocumentationAnchor, Caption,
+    Wrapped, Indented
 }
 
 enum class ListStyle : Style {
-- 
cgit