Underline @param tag key for more consistency (#2643)

* Underline `@param` tag key for more consistency * Correct keyValue table column ratio
Kotlin · Sep 2, 2022 · 56ff8f3 · 56ff8f3
1 parent 7aae28c
commit 56ff8f3
Show file tree

Hide file tree

Showing 15 changed files with 104 additions and 7 deletions.
diff --git a/core/api/core.api b/core/api/core.api
@@ -4294,6 +4294,7 @@ public final class org/jetbrains/dokka/pages/TextStyle : java/lang/Enum, org/jet
 	public static final field Strikethrough Lorg/jetbrains/dokka/pages/TextStyle;
 	public static final field Strong Lorg/jetbrains/dokka/pages/TextStyle;
 	public static final field UnderCoverText Lorg/jetbrains/dokka/pages/TextStyle;
+	public static final field Underlined Lorg/jetbrains/dokka/pages/TextStyle;
 	public static final field Var Lorg/jetbrains/dokka/pages/TextStyle;
 	public static fun valueOf (Ljava/lang/String;)Lorg/jetbrains/dokka/pages/TextStyle;
 	public static fun values ()[Lorg/jetbrains/dokka/pages/TextStyle;

diff --git a/core/src/main/kotlin/pages/ContentNodes.kt b/core/src/main/kotlin/pages/ContentNodes.kt
@@ -388,7 +388,7 @@ enum class TokenStyle : Style {
 enum class TextStyle : Style {
     Bold, Italic, Strong, Strikethrough, Paragraph,
     Block, Span, Monospace, Indented, Cover, UnderCoverText, BreakableAfter, Breakable, InlineComment, Quotation,
-    FloatingRight, Var
+    FloatingRight, Var, Underlined
 }
 
 enum class ContentStyle : Style {

diff --git a/plugins/base/api/base.api b/plugins/base/api/base.api
@@ -563,6 +563,8 @@ public final class org/jetbrains/dokka/base/renderers/html/TagsKt {
 	public static final fun templateCommandAsHtmlComment (Lkotlinx/html/FlowOrMetaDataContent;Lorg/jetbrains/dokka/base/templating/Command;Lkotlin/jvm/functions/Function1;)V
 	public static synthetic fun templateCommandAsHtmlComment$default (Lkotlinx/html/FlowOrMetaDataContent;Lorg/jetbrains/dokka/base/templating/Command;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)V
 	public static final fun templateCommandFor (Lorg/jetbrains/dokka/base/templating/Command;Lkotlinx/html/TagConsumer;)Lorg/jetbrains/dokka/base/renderers/html/TemplateCommand;
+	public static final fun underline (Lkotlinx/html/FlowOrPhrasingContent;Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V
+	public static synthetic fun underline$default (Lkotlinx/html/FlowOrPhrasingContent;Ljava/lang/String;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)V
 	public static final fun wbr (Lkotlinx/html/FlowOrPhrasingContent;Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V
 	public static synthetic fun wbr$default (Lkotlinx/html/FlowOrPhrasingContent;Ljava/lang/String;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)V
 }
@@ -571,6 +573,11 @@ public final class org/jetbrains/dokka/base/renderers/html/TemplateCommand : kot
 	public fun <init> (Ljava/util/Map;Lkotlinx/html/TagConsumer;)V
 }
 
+public class org/jetbrains/dokka/base/renderers/html/UNDERLINE : kotlinx/html/HTMLTag, kotlinx/html/HtmlBlockInlineTag {
+	public fun <init> (Ljava/util/Map;Lkotlinx/html/TagConsumer;)V
+	public fun getConsumer ()Lkotlinx/html/TagConsumer;
+}
+
 public class org/jetbrains/dokka/base/renderers/html/WBR : kotlinx/html/HTMLTag, kotlinx/html/HtmlBlockInlineTag {
 	public fun <init> (Ljava/util/Map;Lkotlinx/html/TagConsumer;)V
 }

diff --git a/plugins/base/base-test-utils/api/base-test-utils.api b/plugins/base/base-test-utils/api/base-test-utils.api
@@ -184,6 +184,10 @@ public final class utils/TestOutputWriterPlugin : org/jetbrains/dokka/plugabilit
 	public final fun getWriter ()Lutils/TestOutputWriter;
 }
 
+public final class utils/U : utils/Tag {
+	public fun <init> ([Ljava/lang/Object;)V
+}
+
 public final class utils/Var : utils/Tag {
 	public fun <init> ([Ljava/lang/Object;)V
 }

diff --git a/plugins/base/base-test-utils/src/main/kotlin/renderers/JsoupUtils.kt b/plugins/base/base-test-utils/src/main/kotlin/renderers/JsoupUtils.kt
@@ -35,6 +35,7 @@ class Dl(vararg matchers: Any) : Tag("dl", *matchers)
 class Dt(vararg matchers: Any) : Tag("dt", *matchers)
 class Dd(vararg matchers: Any) : Tag("dd", *matchers)
 class Var(vararg matchers: Any) : Tag("var", *matchers)
+class U(vararg matchers: Any) : Tag("u", *matchers)
 object Wbr : Tag("wbr")
 object Br : Tag("br")
 

diff --git 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
@@ -26,6 +26,12 @@ inline fun FlowOrPhrasingContent.strike(classes : String? = null, crossinline bl
 open class STRIKE(initialAttributes: Map<String, String>, 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<String, String>, 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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: <u>underlined</u>
+            | */
+            | 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
@@ -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()
-}
+}
diff --git 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 <T> assertContains(iterable: Iterable<T>, element: T, ) {
+    asserter.assertTrue(
+        { "Expected the collection to contain the element.\nCollection <$iterable>, element <$element>." },
+        iterable.contains(element)
+    )
+}
+
 inline fun <reified T : Any> Any?.assertIsInstance(name: String): T =
     this.let { it as? T } ?: throw AssertionError("$name should not be null")