From 56ff8f3f24209bc9edaece876c56bd3fde1fbf8a Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Fri, 2 Sep 2022 17:44:05 +0200 Subject: Underline `@param` tag key for more consistency (#2643) * Underline `@param` tag key for more consistency * Correct keyValue table column ratio --- .../src/main/kotlin/renderers/html/HtmlRenderer.kt | 1 + .../base/src/main/kotlin/renderers/html/Tags.kt | 6 ++++ .../pages/comments/DocTagToContentConverter.kt | 1 + .../documentables/DefaultPageCreator.kt | 2 +- .../translators/psi/parsers/JavadocParser.kt | 1 + .../base/src/main/resources/dokka/styles/style.css | 8 +++++- .../kotlin/content/params/ContentForParamsTest.kt | 20 ++++++++++++-- .../src/test/kotlin/parsers/JavadocParserTest.kt | 32 ++++++++++++++++++++++ .../test/kotlin/renderers/html/TextStylesTest.kt | 14 +++++++++- plugins/base/src/test/kotlin/utils/TestUtils.kt | 11 ++++++++ 10 files changed, 90 insertions(+), 6 deletions(-) (limited to 'plugins/base/src') diff --git a/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt b/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt index f5c3854c..cb7f58d2 100644 --- a/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt +++ b/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt @@ -791,6 +791,7 @@ open class HtmlRenderer( TextStyle.Strikethrough -> strike { body() } TextStyle.Strong -> strong { body() } TextStyle.Var -> htmlVar { body() } + TextStyle.Underlined -> underline { body() } is TokenStyle -> span("token " + styleToApply.toString().toLowerCase()) { body() } else -> body() } diff --git a/plugins/base/src/main/kotlin/renderers/html/Tags.kt b/plugins/base/src/main/kotlin/renderers/html/Tags.kt index ef27b934..18a321cc 100644 --- a/plugins/base/src/main/kotlin/renderers/html/Tags.kt +++ b/plugins/base/src/main/kotlin/renderers/html/Tags.kt @@ -26,6 +26,12 @@ inline fun FlowOrPhrasingContent.strike(classes : String? = null, crossinline bl open class STRIKE(initialAttributes: Map, override val consumer: TagConsumer<*>) : HTMLTag("strike", consumer, initialAttributes, null, false, false), HtmlBlockInlineTag +@HtmlTagMarker +inline fun FlowOrPhrasingContent.underline(classes : String? = null, crossinline block : UNDERLINE.() -> Unit = {}) : Unit = UNDERLINE(attributesMapOf("class", classes), consumer).visit(block) + +open class UNDERLINE(initialAttributes: Map, override val consumer: TagConsumer<*>) : + HTMLTag("u", consumer, initialAttributes, null, false, false), HtmlBlockInlineTag + const val TEMPLATE_COMMAND_SEPARATOR = ":" const val TEMPLATE_COMMAND_BEGIN_BORDER = "[+]cmd" const val TEMPLATE_COMMAND_END_BORDER = "[-]cmd" diff --git a/plugins/base/src/main/kotlin/transformers/pages/comments/DocTagToContentConverter.kt b/plugins/base/src/main/kotlin/transformers/pages/comments/DocTagToContentConverter.kt index 1c447e9e..2193283c 100644 --- a/plugins/base/src/main/kotlin/transformers/pages/comments/DocTagToContentConverter.kt +++ b/plugins/base/src/main/kotlin/transformers/pages/comments/DocTagToContentConverter.kt @@ -255,6 +255,7 @@ open class DocTagToContentConverter : CommentsToContentConverter { ) ) is Var -> buildChildren(docTag, setOf(TextStyle.Var)) + is U -> buildChildren(docTag, setOf(TextStyle.Underlined)) else -> buildChildren(docTag) } diff --git a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt index 7f16c568..12fbb33c 100644 --- a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt +++ b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt @@ -572,7 +572,7 @@ open class DefaultPageCreator( text( it.name, kind = ContentKind.Parameters, - styles = mainStyles + ContentStyle.RowTitle + styles = mainStyles + setOf(ContentStyle.RowTitle, TextStyle.Underlined) ) if (it.isNotEmpty()) { comment(it.root) diff --git a/plugins/base/src/main/kotlin/translators/psi/parsers/JavadocParser.kt b/plugins/base/src/main/kotlin/translators/psi/parsers/JavadocParser.kt index 7dc8e3a0..076d43a2 100644 --- a/plugins/base/src/main/kotlin/translators/psi/parsers/JavadocParser.kt +++ b/plugins/base/src/main/kotlin/translators/psi/parsers/JavadocParser.kt @@ -425,6 +425,7 @@ class JavadocParser( "h2" -> ifChildrenPresent { H2(children) } "h3" -> ifChildrenPresent { H3(children) } "var" -> ifChildrenPresent { Var(children) } + "u" -> ifChildrenPresent { U(children) } else -> listOf(Text(body = element.ownText())) } } diff --git a/plugins/base/src/main/resources/dokka/styles/style.css b/plugins/base/src/main/resources/dokka/styles/style.css index bbab2164..431db3b8 100644 --- a/plugins/base/src/main/resources/dokka/styles/style.css +++ b/plugins/base/src/main/resources/dokka/styles/style.css @@ -709,6 +709,12 @@ a small { display: block; } +u { + text-decoration: none; + padding-bottom: 2px; + border-bottom: 1px solid var(--border-color); +} + blockquote { border-left: 1ch solid var(--default-gray); margin: 0; @@ -1039,7 +1045,7 @@ td.content { @media print, screen and (min-width: 960px) { .keyValue { - grid-template-columns: 25% 75%; + grid-template-columns: 20% 80%; } .title-row { diff --git a/plugins/base/src/test/kotlin/content/params/ContentForParamsTest.kt b/plugins/base/src/test/kotlin/content/params/ContentForParamsTest.kt index 7e11dc85..3531f148 100644 --- a/plugins/base/src/test/kotlin/content/params/ContentForParamsTest.kt +++ b/plugins/base/src/test/kotlin/content/params/ContentForParamsTest.kt @@ -7,10 +7,8 @@ import org.jetbrains.dokka.model.dfs import org.jetbrains.dokka.model.doc.DocumentationNode import org.jetbrains.dokka.model.doc.Param import org.jetbrains.dokka.model.doc.Text -import org.jetbrains.dokka.pages.ContentDRILink -import org.jetbrains.dokka.pages.ContentPage -import org.jetbrains.dokka.pages.MemberPageNode import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest +import org.jetbrains.dokka.pages.* import org.jetbrains.kotlin.utils.addToStdlib.firstIsInstanceOrNull import org.junit.jupiter.api.Test import utils.* @@ -1057,6 +1055,10 @@ class ContentForParamsTest : BaseAbstractTest() { table { group { +"abc" + check { + val textStyles = children.single { it is ContentText }.style + assertContains(textStyles, TextStyle.Underlined) + } group { group { +"comment to param" } } } } @@ -1110,14 +1112,26 @@ class ContentForParamsTest : BaseAbstractTest() { table { group { +"first" + check { + val textStyles = children.single { it is ContentText }.style + assertContains(textStyles, TextStyle.Underlined) + } group { group { +"comment to first param" } } } group { +"second" + check { + val textStyles = children.single { it is ContentText }.style + assertContains(textStyles, TextStyle.Underlined) + } group { group { +"comment to second param" } } } group { +"third" + check { + val textStyles = children.single { it is ContentText }.style + assertContains(textStyles, TextStyle.Underlined) + } group { group { +"comment to third param" } } } } diff --git a/plugins/base/src/test/kotlin/parsers/JavadocParserTest.kt b/plugins/base/src/test/kotlin/parsers/JavadocParserTest.kt index f7911c08..b2397b95 100644 --- a/plugins/base/src/test/kotlin/parsers/JavadocParserTest.kt +++ b/plugins/base/src/test/kotlin/parsers/JavadocParserTest.kt @@ -435,6 +435,38 @@ class JavadocParserTest : BaseAbstractTest() { } } + @Test + fun `u tag is handled properly`() { + val source = """ + |/src/main/kotlin/test/Test.java + |package example + | + | /** + | * An example of using u tag: underlined + | */ + | public class Test {} + """.trimIndent() + testInline( + source, + configuration, + ) { + documentablesCreationStage = { modules -> + val docs = modules.first().packages.first().classlikes.single().documentation.first().value + val root = docs.children.first().root + + assertEquals( + listOf( + P(children = listOf( + Text("An example of using u tag: "), + U(children = listOf(Text("underlined"))), + )), + ), + root.children + ) + } + } + } + @Test fun `undocumented see also from java`(){ testInline( diff --git a/plugins/base/src/test/kotlin/renderers/html/TextStylesTest.kt b/plugins/base/src/test/kotlin/renderers/html/TextStylesTest.kt index 98f73ffa..507f1779 100644 --- a/plugins/base/src/test/kotlin/renderers/html/TextStylesTest.kt +++ b/plugins/base/src/test/kotlin/renderers/html/TextStylesTest.kt @@ -92,6 +92,18 @@ class TextStylesTest : HtmlRenderingOnlyTestBase() { renderedContent.match(Var("variable")) } + @Test + fun `should include underlined text`() { + val page = testPage { + group(styles = setOf(TextStyle.Underlined)) { + text("underlined text") + } + } + HtmlRenderer(context).render(page) + println(renderedContent) + renderedContent.match(U("underlined text")) + } + override val renderedContent: Element get() = files.contents.getValue("test-page.html").let { Jsoup.parse(it) }.select("#content").single() -} \ No newline at end of file +} diff --git a/plugins/base/src/test/kotlin/utils/TestUtils.kt b/plugins/base/src/test/kotlin/utils/TestUtils.kt index e4bc4a1e..8cb126d5 100644 --- a/plugins/base/src/test/kotlin/utils/TestUtils.kt +++ b/plugins/base/src/test/kotlin/utils/TestUtils.kt @@ -7,6 +7,7 @@ import org.jetbrains.dokka.model.doc.P import org.junit.jupiter.api.Assertions.assertEquals import org.junit.jupiter.api.Assertions.assertTrue import kotlin.collections.orEmpty +import kotlin.test.asserter @DslMarker annotation class TestDSL @@ -38,6 +39,16 @@ interface AssertDSL { assert(count() == n) { "${prefix}Expected $n, got ${count()}" } } +/* + * TODO replace with kotlin.test.assertContains after migrating to Kotlin 1.5+ + */ +internal fun assertContains(iterable: Iterable, element: T, ) { + asserter.assertTrue( + { "Expected the collection to contain the element.\nCollection <$iterable>, element <$element>." }, + iterable.contains(element) + ) +} + inline fun Any?.assertIsInstance(name: String): T = this.let { it as? T } ?: throw AssertionError("$name should not be null") -- cgit