Don't force @literal in javadoc to be surrounded by code tag (#2089)

* Don't force @literal in javadoc to be surrounded by code tag

* Enclose in <literal> tag and add test for angle brackets

2 files changed, 114 insertions, 2 deletions

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 8583edf7..8bc950b7 100644
--- a/plugins/base/src/main/kotlin/translators/psi/parsers/JavadocParser.kt
+++ b/plugins/base/src/main/kotlin/translators/psi/parsers/JavadocParser.kt
@@ -333,8 +333,8 @@ class JavadocParser(
             when (tag.name) {
                 "link", "linkplain" -> tag.referenceElement()
                     ?.toDocumentationLinkString(tag.dataElements.filterIsInstance<PsiDocToken>())
-                "code", "literal" -> "<code data-inline>${tag.dataElements.joinToString("") { it.stringifyElementAsText(keepFormatting = true)
-                    .toString() }.htmlEscape()}</code>"
+                "code" -> "<code data-inline>${dataElementsAsText(tag)}</code>"
+                "literal" -> "<literal>${dataElementsAsText(tag)}</literal>"
                 "index" -> "<index>${tag.children.filterIsInstance<PsiDocTagValue>().joinToString { it.text }}</index>"
                 "inheritDoc" -> inheritDocResolver.resolveFromContext(context)
                     ?.fold(ParsingResult(javadocTag)) { result, e ->
@@ -343,6 +343,11 @@ class JavadocParser(
                 else -> tag.text
             }
 
+        private fun dataElementsAsText(tag: PsiInlineDocTag) =
+            tag.dataElements.joinToString("") {
+                it.stringifyElementAsText(keepFormatting = true).toString()
+            }.htmlEscape()
+
         private fun createLink(element: Element, children: List<DocTag>): DocTag {
             return when {
                 element.hasAttr("docref") ->
diff --git a/plugins/base/src/test/kotlin/parsers/JavadocParserTest.kt b/plugins/base/src/test/kotlin/parsers/JavadocParserTest.kt
index d6fffee3..bdb1af86 100644
--- a/plugins/base/src/test/kotlin/parsers/JavadocParserTest.kt
+++ b/plugins/base/src/test/kotlin/parsers/JavadocParserTest.kt
@@ -6,6 +6,8 @@ import org.jetbrains.dokka.model.DEnum
 import org.jetbrains.dokka.model.DModule
 import org.jetbrains.dokka.model.doc.CodeBlock
 import org.jetbrains.dokka.model.doc.CodeInline
+import org.jetbrains.dokka.model.doc.P
+import org.jetbrains.dokka.model.doc.Pre
 import org.jetbrains.dokka.model.doc.Text
 import org.junit.jupiter.api.Assertions.assertEquals
 import org.junit.jupiter.api.Test
@@ -107,4 +109,109 @@ class JavadocParserTest : BaseAbstractTest() {
             }
         }
     }
+
+    @Test
+    fun `literal tag`() {
+        val source = """
+            |/src/main/kotlin/test/Test.java
+            |package example
+            |
+            | /**
+            | * An example of using the literal tag
+            | * {@literal @}Entity
+            | * public class User {}
+            | */
+            | 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(
+                        Text(body = "An example of using the literal tag "),
+                        Text(body = "@"),
+                        Text(body = "Entity public class User {}"),
+                    ),
+                    root.children.first().children
+                )
+            }
+        }
+    }
+
+    @Test
+    fun `literal tag nested under pre tag`() {
+        val source = """
+            |/src/main/kotlin/test/Test.java
+            |package example
+            |
+            | /**
+            | * An example of using the literal tag
+            | * <pre>
+            | * {@literal @}Entity
+            | * public class User {}
+            | * </pre>
+            | */
+            | 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(body = "An example of using the literal tag "))),
+                        Pre(children =
+                            listOf(
+                                Text(body = "@"),
+                                Text(body = "Entity\npublic class User {}\n")
+                            )
+                        )
+                    ),
+                    root.children
+                )
+            }
+        }
+    }
+
+    @Test
+    fun `literal tag containing angle brackets`() {
+        val source = """
+            |/src/main/kotlin/test/Test.java
+            |package example
+            |
+            | /**
+            | * An example of using the literal tag
+            | * {@literal a<B>c}
+            | */
+            | 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(body = "An example of using the literal tag "),
+                            Text(body = "a<B>c")
+                        )),
+                    ),
+                    root.children
+                )
+            }
+        }
+    }
 }