Apply the same style to all KDoc tags, including throws/see/parameters (#2587)

3 files changed, 41 insertions, 22 deletions

diff --git a/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt b/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt
index a28fcd04..b586b95e 100644
--- a/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt
+++ b/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt
@@ -96,6 +96,7 @@ open class HtmlRenderer(
             node.dci.kind in setOf(ContentKind.Symbol) -> div("symbol $additionalClasses") {
                 childrenCallback()
             }
+            node.hasStyle(ContentStyle.KDocTag) -> span("kdoc-tag") { childrenCallback() }
             node.hasStyle(TextStyle.BreakableAfter) -> {
                 span { childrenCallback() }
                 wbr { }
diff --git a/plugins/base/src/main/kotlin/transformers/pages/tags/SinceKotlinTagContentProvider.kt b/plugins/base/src/main/kotlin/transformers/pages/tags/SinceKotlinTagContentProvider.kt
index c9010421..a1d30903 100644
--- a/plugins/base/src/main/kotlin/transformers/pages/tags/SinceKotlinTagContentProvider.kt
+++ b/plugins/base/src/main/kotlin/transformers/pages/tags/SinceKotlinTagContentProvider.kt
@@ -1,9 +1,9 @@
 package org.jetbrains.dokka.base.transformers.pages.tags
 
 import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.base.translators.documentables.KDOC_TAG_HEADER_LEVEL
 import org.jetbrains.dokka.base.translators.documentables.PageContentBuilder.DocumentableContentBuilder
 import org.jetbrains.dokka.model.doc.CustomTagWrapper
-import org.jetbrains.dokka.pages.ContentKind
 import org.jetbrains.dokka.pages.TextStyle
 
 object SinceKotlinTagContentProvider : CustomTagContentProvider {
@@ -16,8 +16,8 @@ object SinceKotlinTagContentProvider : CustomTagContentProvider {
         sourceSet: DokkaConfiguration.DokkaSourceSet,
         customTag: CustomTagWrapper
     ) {
-        group(sourceSets = setOf(sourceSet), kind = ContentKind.Comment, styles = setOf(TextStyle.Block)) {
-            header(4, customTag.name)
+        group(sourceSets = setOf(sourceSet), styles = emptySet()) {
+            header(KDOC_TAG_HEADER_LEVEL, customTag.name)
             comment(customTag.root)
         }
     }
@@ -31,4 +31,4 @@ object SinceKotlinTagContentProvider : CustomTagContentProvider {
             comment(customTag.root, styles = emptySet())
         }
     }
-}
\ No newline at end of file
+}
diff --git a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt
index a8b33d4c..f08b2056 100644
--- a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt
+++ b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt
@@ -21,6 +21,8 @@ import org.jetbrains.kotlin.utils.addToStdlib.safeAs
 import kotlin.reflect.KClass
 import kotlin.reflect.full.isSubclassOf
 
+internal const val KDOC_TAG_HEADER_LEVEL = 4
+
 private typealias GroupedTags = Map<KClass<out TagWrapper>, List<Pair<DokkaSourceSet?, TagWrapper>>>
 
 private val specialTags: Set<KClass<out TagWrapper>> =
@@ -463,11 +465,11 @@ open class DefaultPageCreator(
 
             val customTags = d.customTags
             if (customTags.isNotEmpty()) {
-                group(styles = setOf(TextStyle.Block)) {
-                    platforms.forEach { platform ->
-                        customTags.forEach { (_, sourceSetTag) ->
-                            sourceSetTag[platform]?.let { tag ->
-                                customTagContentProviders.filter { it.isApplicable(tag) }.forEach { provider ->
+                platforms.forEach { platform ->
+                    customTags.forEach { (_, sourceSetTag) ->
+                        sourceSetTag[platform]?.let { tag ->
+                            customTagContentProviders.filter { it.isApplicable(tag) }.forEach { provider ->
+                                group(sourceSets = setOf(platform), styles = setOf(ContentStyle.KDocTag)) {
                                     with(provider) {
                                         contentForDescription(platform, tag)
                                     }
@@ -485,9 +487,13 @@ open class DefaultPageCreator(
                     unnamedTags[platform]?.let { tags ->
                         if (tags.isNotEmpty()) {
                             tags.groupBy { it::class }.forEach { (_, sameCategoryTags) ->
-                                group(sourceSets = setOf(platform), styles = emptySet()) {
-                                    header(4, sameCategoryTags.first().toHeaderString())
-                                    sameCategoryTags.forEach { comment(it.root) }
+                                group(sourceSets = setOf(platform), styles = setOf(ContentStyle.KDocTag)) {
+                                    header(
+                                        level = KDOC_TAG_HEADER_LEVEL,
+                                        text = sameCategoryTags.first().toHeaderString(),
+                                        styles = setOf()
+                                    )
+                                    sameCategoryTags.forEach { comment(it.root, styles = setOf()) }
                                 }
                             }
                         }
@@ -537,7 +543,7 @@ open class DefaultPageCreator(
                 val params = tags.withTypeNamed<Param>()
                 val availablePlatforms = params.values.flatMap { it.keys }.toSet()
 
-                header(2, "Parameters", kind = ContentKind.Parameters, sourceSets = availablePlatforms)
+                header(KDOC_TAG_HEADER_LEVEL, "Parameters", kind = ContentKind.Parameters, sourceSets = availablePlatforms)
                 group(
                     extra = mainExtra + SimpleAttr.header("Parameters"),
                     styles = setOf(ContentStyle.WithExtraAttributes),
@@ -555,7 +561,9 @@ open class DefaultPageCreator(
                                                 kind = ContentKind.Parameters,
                                                 styles = mainStyles + ContentStyle.RowTitle
                                             )
-                                            comment(it.root)
+                                            if (it.isNotEmpty()) {
+                                                comment(it.root)
+                                            }
                                         }
                                     }
                                 }
@@ -571,7 +579,7 @@ open class DefaultPageCreator(
                 val seeAlsoTags = tags.withTypeNamed<See>()
                 val availablePlatforms = seeAlsoTags.values.flatMap { it.keys }.toSet()
 
-                header(2, "See also", kind = ContentKind.Comment, sourceSets = availablePlatforms)
+                header(KDOC_TAG_HEADER_LEVEL, "See also", kind = ContentKind.Comment, sourceSets = availablePlatforms)
                 group(
                     extra = mainExtra + SimpleAttr.header("See also"),
                     styles = setOf(ContentStyle.WithExtraAttributes),
@@ -590,7 +598,7 @@ open class DefaultPageCreator(
                                         ) {
                                             it.address?.let { dri ->
                                                 link(
-                                                    it.name,
+                                                    dri.classNames ?: it.name,
                                                     dri,
                                                     kind = ContentKind.Comment,
                                                     styles = mainStyles + ContentStyle.RowTitle
@@ -600,7 +608,9 @@ open class DefaultPageCreator(
                                                 kind = ContentKind.Comment,
                                                 styles = mainStyles + ContentStyle.RowTitle
                                             )
-                                            comment(it.root)
+                                            if (it.isNotEmpty()) {
+                                                comment(it.root)
+                                            }
                                         }
                                     }
                                 }
@@ -616,19 +626,25 @@ open class DefaultPageCreator(
             if (throws.isNotEmpty()) {
                 val availablePlatforms = throws.values.flatMap { it.keys }.toSet()
 
-                header(2, "Throws", sourceSets = availablePlatforms)
+                header(KDOC_TAG_HEADER_LEVEL, "Throws", sourceSets = availablePlatforms)
                 buildContent(availablePlatforms) {
                     availablePlatforms.forEach { sourceset ->
-                        table(kind = ContentKind.Main, sourceSets = setOf(sourceset)) {
+                        table(
+                            kind = ContentKind.Main,
+                            sourceSets = setOf(sourceset),
+                            extra = mainExtra + SimpleAttr.header("Throws")
+                        ) {
                             throws.entries.forEach { entry ->
                                 entry.value[sourceset]?.let { throws ->
                                     row(sourceSets = setOf(sourceset)) {
                                         group(styles = mainStyles + ContentStyle.RowTitle) {
                                             throws.exceptionAddress?.let {
-                                                link(text = entry.key, address = it)
+                                                link(text = it.classNames ?: entry.key, address = it)
                                             } ?: text(entry.key)
                                         }
-                                        comment(throws.root)
+                                        if (throws.isNotEmpty()) {
+                                            comment(throws.root)
+                                        }
                                     }
                                 }
                             }
@@ -642,7 +658,7 @@ open class DefaultPageCreator(
             val samples = tags.withTypeNamed<Sample>()
             if (samples.isNotEmpty()) {
                 val availablePlatforms = samples.values.flatMap { it.keys }.toSet()
-                header(2, "Samples", kind = ContentKind.Sample, sourceSets = availablePlatforms)
+                header(KDOC_TAG_HEADER_LEVEL, "Samples", kind = ContentKind.Sample, sourceSets = availablePlatforms)
                 group(
                     extra = mainExtra + SimpleAttr.header("Samples"),
                     styles = emptySet(),
@@ -676,6 +692,8 @@ open class DefaultPageCreator(
         }.children
     }
 
+    private fun TagWrapper.isNotEmpty() = this.children.isNotEmpty()
+
     protected open fun DocumentableContentBuilder.contentForBrief(documentable: Documentable) {
         documentable.sourceSets.forEach { sourceSet ->
             documentable.documentation[sourceSet]?.let {