Wrap long signatures dynamically based on client width (#2659)

4 files changed, 14 insertions, 32 deletions

diff --git a/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt b/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt
index dfc4e2e3..d949d432 100644
--- a/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt
+++ b/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt
@@ -112,11 +112,6 @@ open class HtmlRenderer(
             }
             node.dci.kind == SymbolContentKind.Parameter -> {
                 span("parameter $additionalClasses") {
-                    if (node.hasStyle(ContentStyle.Indented)) {
-                        // could've been done with CSS (padding-left, ::before, etc), but the indent needs to
-                        // consist of physical spaces, otherwise select and copy won't work properly
-                        repeat(4) { consumer.onTagContentEntity(Entities.nbsp) }
-                    }
                     childrenCallback()
                 }
             }
diff --git a/plugins/base/src/main/kotlin/renderers/html/htmlPreprocessors.kt b/plugins/base/src/main/kotlin/renderers/html/htmlPreprocessors.kt
index 2de6f2b7..e2be3ef0 100644
--- a/plugins/base/src/main/kotlin/renderers/html/htmlPreprocessors.kt
+++ b/plugins/base/src/main/kotlin/renderers/html/htmlPreprocessors.kt
@@ -45,12 +45,20 @@ class CustomResourceInstaller(val dokkaContext: DokkaContext) : PageTransformer
 }
 
 class ScriptsInstaller(private val dokkaContext: DokkaContext) : PageTransformer {
+
+    // scripts ending with `_deferred.js` are loaded with `defer`, otherwise `async`
     private val scriptsPages = listOf(
         "scripts/clipboard.js",
         "scripts/navigation-loader.js",
         "scripts/platform-content-handler.js",
         "scripts/main.js",
-        "scripts/prism.js"
+        "scripts/prism.js",
+
+        // It's important for this script to be deferred because it has logic that makes decisions based on
+        // rendered elements (for instance taking their clientWidth), and if not all styles are loaded/applied
+        // at the time of inspecting them, it will give incorrect results and might lead to visual bugs.
+        // should be easy to test if you open any page in incognito or by reloading it (Ctrl+Shift+R)
+        "scripts/symbol-parameters-wrapper_deferred.js",
     )
 
     override fun invoke(input: RootPageNode): RootPageNode =
diff --git a/plugins/base/src/main/kotlin/renderers/html/innerTemplating/DefaultTemplateModelFactory.kt b/plugins/base/src/main/kotlin/renderers/html/innerTemplating/DefaultTemplateModelFactory.kt
index 9f1ca57e..6c746b37 100644
--- a/plugins/base/src/main/kotlin/renderers/html/innerTemplating/DefaultTemplateModelFactory.kt
+++ b/plugins/base/src/main/kotlin/renderers/html/innerTemplating/DefaultTemplateModelFactory.kt
@@ -102,7 +102,7 @@ class DefaultTemplateModelFactory(val context: DokkaContext) : TemplateModelFact
                             type = ScriptType.textJavaScript,
                             src = if (it.isAbsolute) it else "$pathToRoot$it"
                         ) {
-                            if (it == "scripts/main.js")
+                            if (it == "scripts/main.js" || it.endsWith("_deferred.js"))
                                 defer = true
                             else
                                 async = true
@@ -204,4 +204,4 @@ private class TemplateDirective(val configuration: DokkaConfiguration, val pathT
         const val PARAM_NAME = "name"
         const val PARAM_REPLACEMENT = "replacement"
     }
-}
\ No newline at end of file
+}
diff --git a/plugins/base/src/main/kotlin/signatures/JvmSignatureUtils.kt b/plugins/base/src/main/kotlin/signatures/JvmSignatureUtils.kt
index 7ed7ff3f..f6c4f0db 100644
--- a/plugins/base/src/main/kotlin/signatures/JvmSignatureUtils.kt
+++ b/plugins/base/src/main/kotlin/signatures/JvmSignatureUtils.kt
@@ -202,39 +202,18 @@ interface JvmSignatureUtils {
     fun PageContentBuilder.DocumentableContentBuilder.parametersBlock(
         function: DFunction, paramBuilder: PageContentBuilder.DocumentableContentBuilder.(DParameter) -> Unit
     ) {
-        val shouldWrap = function.shouldWrapParams()
-        val parametersStyle = if (shouldWrap) setOf(ContentStyle.Wrapped) else emptySet()
-        val elementStyle = if (shouldWrap) setOf(ContentStyle.Indented) else emptySet()
-        group(kind = SymbolContentKind.Parameters, styles = parametersStyle) {
+        group(kind = SymbolContentKind.Parameters, styles = emptySet()) {
             function.parameters.dropLast(1).forEach {
-                group(kind = SymbolContentKind.Parameter, styles = elementStyle) {
+                group(kind = SymbolContentKind.Parameter) {
                     paramBuilder(it)
                     punctuation(", ")
                 }
             }
-            group(kind = SymbolContentKind.Parameter, styles = elementStyle) {
+            group(kind = SymbolContentKind.Parameter) {
                 paramBuilder(function.parameters.last())
             }
         }
     }
-
-    /**
-     * Determines whether parameters in a function (including constructor) should be wrapped
-     *
-     * Without wrapping:
-     * ```
-     * class SimpleClass(foo: String, bar: String) {}
-     * ```
-     * With wrapping:
-     * ```
-     * class SimpleClass(
-     *     foo: String,
-     *     bar: String,
-     *     baz: String
-     * )
-     * ```
-     */
-    private fun DFunction.shouldWrapParams() = this.parameters.size >= 3
 }
 
 sealed class AtStrategy