Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 3 commits into from Aug 3, 2022
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1edeb01
Apply the same style to all KDoc tags, including throws/see/parameters
IgnatBeresnev Jul 26, 2022
bef3ced
Extract header level into a constant and fix SinceKotlin styling
IgnatBeresnev Jul 27, 2022
c96b1e7
[Regression] Fix main description paragraphs not having any padding
IgnatBeresnev Jul 28, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
1 change: 1 addition & 0 deletions core/api/core.api
View file
Open in desktop
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
Open in desktop
Expand Up @@ -388,7 +388,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
Open in desktop
Expand Up @@ -97,6 +97,7 @@ open class HtmlRenderer(
childrenCallback()
if (node.hasStyle(TextStyle.Monospace)) copyButton()
}
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
Open in desktop
@@ -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
Open in desktop
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
Open in desktop
Expand Up @@ -237,6 +237,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 @@ -943,11 +951,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