Skip to content

Commit

Permalink
Apply the same style to all KDoc tags, including throws/see/parameters (
Browse files Browse the repository at this point in the history 
#2587)
  • Loading branch information
@IgnatBeresnev
IgnatBeresnev committed Aug 3, 2022
1 parent 018af7d commit 3994c42
Show file tree
Hide file tree
Showing 8 changed files with 180 additions and 54 deletions.
1 change: 1 addition & 0 deletions core/api/core.api
View file
Expand Up @@ -3912,6 +3912,7 @@ public final class org/jetbrains/dokka/pages/ContentStyle : java/lang/Enum, org/
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 KDocTag 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;
Expand Down
2 changes: 1 addition & 1 deletion core/src/main/kotlin/pages/ContentNodes.kt
View file
Expand Up @@ -389,7 +389,7 @@ enum class TextStyle : Style {

enum class ContentStyle : Style {
RowTitle, TabbedContent, WithExtraAttributes, RunnableSample, InDocumentationAnchor, Caption,
Wrapped, Indented
Wrapped, Indented, KDocTag
}

enum class ListStyle : Style {
Expand Down
1 change: 1 addition & 0 deletions plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt
View file
Expand Up @@ -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 { }
Expand Down
8 changes: 4 additions & 4 deletions plugins/base/src/main/kotlin/transformers/pages/tags/SinceKotlinTagContentProvider.kt
View file
@@ -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 {
Expand All @@ -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)
}
}
Expand All @@ -31,4 +31,4 @@ object SinceKotlinTagContentProvider : CustomTagContentProvider {
comment(customTag.root, styles = emptySet())
}
}
}
}
54 changes: 36 additions & 18 deletions plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt
View file
Expand Up @@ -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>> =
Expand Down Expand Up @@ -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)
}
Expand All @@ -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()) }
}
}
}
Expand Down Expand Up @@ -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),
Expand All @@ -555,7 +561,9 @@ open class DefaultPageCreator(
kind = ContentKind.Parameters,
styles = mainStyles + ContentStyle.RowTitle
)
comment(it.root)
if (it.isNotEmpty()) {
comment(it.root)
}
}
}
}
Expand All @@ -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),
Expand All @@ -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
Expand All @@ -600,7 +608,9 @@ open class DefaultPageCreator(
kind = ContentKind.Comment,
styles = mainStyles + ContentStyle.RowTitle
)
comment(it.root)
if (it.isNotEmpty()) {
comment(it.root)
}
}
}
}
Expand All @@ -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)
}
}
}
}
Expand All @@ -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(),
Expand Down Expand Up @@ -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 {
Expand Down
11 changes: 10 additions & 1 deletion plugins/base/src/main/resources/dokka/styles/style.css
View file
Expand Up @@ -239,6 +239,14 @@ p.paragraph:first-child,
margin-top: 0;
}

.content .kdoc-tag > p.paragraph {
margin-top: 0;
}

.content h4 {
margin-bottom: 0;
}

.divergent-group {
background-color: var(--background-color);
padding: 16px 0 8px 0;
Expand Down Expand Up @@ -1016,11 +1024,12 @@ td.content {

.keyValue {
display: grid;
grid-gap: 8px;
}

@media print, screen and (min-width: 960px) {
.keyValue {
grid-template-columns: 20% 80%;
grid-template-columns: 25% 75%;
}

.title-row {
Expand Down

0 comments on commit 3994c42

Please sign in to comment.