Support of var html tag for Javadoc

Fix #2358
Kotlin · Aug 10, 2022 · ce7a732 · ce7a732
1 parent efed96e
commit ce7a732
Show file tree

Hide file tree

Showing 9 changed files with 54 additions and 1 deletion.
diff --git a/core/api/core.api b/core/api/core.api
@@ -4292,6 +4292,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 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
@@ -383,7 +383,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
+    FloatingRight, Var
 }
 
 enum class ContentStyle : Style {

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/Var : utils/Tag {
+	public fun <init> ([Ljava/lang/Object;)V
+}
+
 public final class utils/Wbr : utils/Tag {
 	public static final field INSTANCE Lutils/Wbr;
 }

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
@@ -34,6 +34,7 @@ class BlockQuote(vararg matchers: Any) : Tag("blockquote", *matchers)
 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)
 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
@@ -777,6 +777,7 @@ open class HtmlRenderer(
             TextStyle.Italic -> i { body() }
             TextStyle.Strikethrough -> strike { body() }
             TextStyle.Strong -> strong { body() }
+            TextStyle.Var -> htmlVar { body() }
             is TokenStyle -> span("token " + styleToApply.toString().toLowerCase()) { body() }
             else -> body()
         }

diff --git a/plugins/base/src/main/kotlin/transformers/pages/comments/DocTagToContentConverter.kt b/plugins/base/src/main/kotlin/transformers/pages/comments/DocTagToContentConverter.kt
@@ -254,6 +254,7 @@ open class DocTagToContentConverter : CommentsToContentConverter {
                     extra = extras
                 )
             )
+            is Var -> buildChildren(docTag, setOf(TextStyle.Var))
 
             else -> buildChildren(docTag)
         }

diff --git a/plugins/base/src/main/kotlin/translators/psi/parsers/JavadocParser.kt b/plugins/base/src/main/kotlin/translators/psi/parsers/JavadocParser.kt
@@ -424,6 +424,7 @@ class JavadocParser(
                 "h1" -> ifChildrenPresent { H1(children) }
                 "h2" -> ifChildrenPresent { H2(children) }
                 "h3" -> ifChildrenPresent { H3(children) }
+                "var" -> ifChildrenPresent { Var(children) }
                 else -> listOf(Text(body = element.ownText()))
             }
         }

diff --git a/plugins/base/src/test/kotlin/parsers/JavadocParserTest.kt b/plugins/base/src/test/kotlin/parsers/JavadocParserTest.kt
@@ -396,4 +396,36 @@ class JavadocParserTest : BaseAbstractTest() {
             }
         }
     }
+
+    @Test
+    fun `var tag is handled properly`() {
+        val source = """
+            |/src/main/kotlin/test/Test.java
+            |package example
+            |
+            | /**
+            | * An example of using var tag: <var>variable</var>
+            | */
+            | 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
+
+                kotlin.test.assertEquals(
+                    listOf(
+                        P(children = listOf(
+                            Text("An example of using var tag: "),
+                            Var(children = listOf(Text("variable"))),
+                        )),
+                    ),
+                    root.children
+                )
+            }
+        }
+    }
 }
diff --git a/plugins/base/src/test/kotlin/renderers/html/TextStylesTest.kt b/plugins/base/src/test/kotlin/renderers/html/TextStylesTest.kt
@@ -80,6 +80,18 @@ class TextStylesTest : HtmlRenderingOnlyTestBase() {
         renderedContent.match(BlockQuote("blockquote text"))
     }
 
+    @Test
+    fun `should include var`() {
+        val page = testPage {
+            group(styles = setOf(TextStyle.Var)) {
+                text("variable")
+            }
+        }
+        HtmlRenderer(context).render(page)
+        println(renderedContent)
+        renderedContent.match(Var("variable"))
+    }
+
     override val renderedContent: Element
         get() = files.contents.getValue("test-page.html").let { Jsoup.parse(it) }.select("#content").single()
 }