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 1 commit
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
30 changes: 20 additions & 10 deletions plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt
View file
Open in desktop
Expand Up @@ -537,7 +537,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(4, "Parameters", kind = ContentKind.Parameters, sourceSets = availablePlatforms)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is better to make a constant to avoid magic number.

group(
extra = mainExtra + SimpleAttr.header("Parameters"),
styles = setOf(ContentStyle.WithExtraAttributes),
Expand All @@ -555,7 +555,9 @@ open class DefaultPageCreator(
kind = ContentKind.Parameters,
styles = mainStyles + ContentStyle.RowTitle
)
comment(it.root)
if (it.root.children.isNotEmpty()) {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would create a helper like TagWrapper.isEmpty() = children.isEmpty() (Law of Demeter)

comment(it.root)
}
}
}
}
Expand All @@ -571,7 +573,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(4, "See also", kind = ContentKind.Comment, sourceSets = availablePlatforms)
group(
extra = mainExtra + SimpleAttr.header("See also"),
styles = setOf(ContentStyle.WithExtraAttributes),
Expand All @@ -590,7 +592,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 +602,9 @@ open class DefaultPageCreator(
kind = ContentKind.Comment,
styles = mainStyles + ContentStyle.RowTitle
)
comment(it.root)
if (it.root.children.isNotEmpty()) {
comment(it.root)
}
}
}
}
Expand All @@ -616,19 +620,25 @@ open class DefaultPageCreator(
if (throws.isNotEmpty()) {
val availablePlatforms = throws.values.flatMap { it.keys }.toSet()

header(2, "Throws", sourceSets = availablePlatforms)
header(4, "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.root.children.isNotEmpty()) {
comment(throws.root)
}
}
}
}
Expand All @@ -642,7 +652,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(4, "Samples", kind = ContentKind.Sample, sourceSets = availablePlatforms)
group(
extra = mainExtra + SimpleAttr.header("Samples"),
styles = emptySet(),
Expand Down
8 changes: 6 additions & 2 deletions plugins/base/src/main/resources/dokka/styles/style.css
View file
Open in desktop
Expand Up @@ -227,11 +227,14 @@ html ::-webkit-scrollbar-thumb {
width: 100%;
}

.main-content p.paragraph,
.sample-container {
margin-top: 8px;
}

.content > h4 {
margin-bottom: 0;
}

p.paragraph:first-child,
.brief p.paragraph {
margin-top: 0;
Expand Down Expand Up @@ -943,11 +946,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
79 changes: 62 additions & 17 deletions plugins/base/src/test/kotlin/content/params/ContentForParamsTest.kt
View file
Open in desktop
Expand Up @@ -450,17 +450,17 @@ class ContentForParamsTest : BaseAbstractTest() {
}
after {
group { pWrapped("a normal comment") }
header(2) { +"Throws" }
header(4) { +"Throws" }
table {
group {
group {
link { +"java.lang.IllegalStateException" }
link { +"IllegalStateException" }
}
comment { +"if the Dialog has not yet been created (before onCreateDialog) or has been destroyed (after onDestroyView)." }
}
group {
group {
link { +"java.lang.RuntimeException" }
link { +"RuntimeException" }
}
comment {
+"when "
Expand Down Expand Up @@ -507,7 +507,7 @@ class ContentForParamsTest : BaseAbstractTest() {
}
after {
group { pWrapped("a normal comment") }
header(2) { +"Throws" }
header(4) { +"Throws" }
table {
group {
group {
Expand All @@ -518,7 +518,7 @@ class ContentForParamsTest : BaseAbstractTest() {
(this as ContentDRILink).address.toString()
)
}
+"java.lang.IllegalStateException"
+"IllegalStateException"
}
}
comment { +"if the Dialog has not yet been created (before onCreateDialog) or has been destroyed (after onDestroyView)." }
Expand All @@ -532,7 +532,7 @@ class ContentForParamsTest : BaseAbstractTest() {
(this as ContentDRILink).address.toString()
)
}
+"java.lang.RuntimeException"
+"RuntimeException"
}
}
comment {
Expand All @@ -550,6 +550,51 @@ class ContentForParamsTest : BaseAbstractTest() {
}
}

@Test
fun `should display fully qualified throws name for unresolved class`() {
testInline(
"""
|/src/main/kotlin/sample/sample.kt
|package sample;
| /**
| * a normal comment
| *
| * @throws com.example.UnknownException description for non-resolved
| */
| fun sample(){ }
""".trimIndent(), testConfiguration
) {
pagesTransformationStage = { module ->
val functionPage =
module.children.single { it.name == "sample" }.children.single { it.name == "sample" } as ContentPage
functionPage.content.assertNode {
group {
header(1) { +"sample" }
}
divergentGroup {
divergentInstance {
divergent {
skipAllNotMatching() //Signature
}
after {
group { pWrapped("a normal comment") }
header(4) { +"Throws" }
table {
group {
group {
+"com.example.UnknownException"
}
comment { +"description for non-resolved" }
}
}
}
}
}
}
}
}
}

@Test
fun `multiline throws where exception is not in the same line as description`() {
testInline(
Expand Down Expand Up @@ -585,7 +630,7 @@ class ContentForParamsTest : BaseAbstractTest() {
}
after {
group { pWrapped("a normal comment") }
header(2) { +"Throws" }
header(4) { +"Throws" }
table {
group {
group {
Expand All @@ -596,7 +641,7 @@ class ContentForParamsTest : BaseAbstractTest() {
(this as ContentDRILink).address.toString()
)
}
+"java.lang.IllegalStateException"
+"IllegalStateException"
}
}
comment { +"if the Dialog has not yet been created (before onCreateDialog) or has been destroyed (after onDestroyView)." }
Expand All @@ -610,7 +655,7 @@ class ContentForParamsTest : BaseAbstractTest() {
(this as ContentDRILink).address.toString()
)
}
+"java.lang.RuntimeException"
+"RuntimeException"
}
}
comment {
Expand Down Expand Up @@ -719,7 +764,7 @@ class ContentForParamsTest : BaseAbstractTest() {
+" doesn't contain value."
}
}
header(2) { +"Parameters" }
header(4) { +"Parameters" }
group {
table {
group {
Expand Down Expand Up @@ -1007,7 +1052,7 @@ class ContentForParamsTest : BaseAbstractTest() {
}
after {
group { pWrapped("comment to function") }
header(2) { +"Parameters" }
header(4) { +"Parameters" }
group {
table {
group {
Expand Down Expand Up @@ -1060,7 +1105,7 @@ class ContentForParamsTest : BaseAbstractTest() {
}
after {
group { group { group { +"comment to function" } } }
header(2) { +"Parameters" }
header(4) { +"Parameters" }
group {
table {
group {
Expand Down Expand Up @@ -1122,7 +1167,7 @@ class ContentForParamsTest : BaseAbstractTest() {
}
after {
group { group { group { +"comment to function" } } }
header(2) { +"Parameters" }
header(4) { +"Parameters" }
group {
table {
group {
Expand Down Expand Up @@ -1181,7 +1226,7 @@ class ContentForParamsTest : BaseAbstractTest() {
)
}
after {
header(2) { +"Parameters" }
header(4) { +"Parameters" }
group {
table {
group {
Expand Down Expand Up @@ -1249,7 +1294,7 @@ class ContentForParamsTest : BaseAbstractTest() {
header(4) { +"Receiver" }
pWrapped("comment to receiver")
}
header(2) { +"Parameters" }
header(4) { +"Parameters" }
group {
table {
group {
Expand Down Expand Up @@ -1301,7 +1346,7 @@ class ContentForParamsTest : BaseAbstractTest() {
}
after {
group { group { group { +"comment to function" } } }
header(2) { +"Parameters" }
header(4) { +"Parameters" }
group {
table {
group {
Expand Down Expand Up @@ -1362,7 +1407,7 @@ class ContentForParamsTest : BaseAbstractTest() {
group { pWrapped("comment to function") }
unnamedTag("Author") { comment { +"Kordyjan" } }
unnamedTag("Since") { comment { +"0.11" } }
header(2) { +"Parameters" }
header(4) { +"Parameters" }

group {
table {
Expand Down