Draft for improving code formatting #1346

7 files changed, 132 insertions, 52 deletions

diff --git a/plugins/base/src/main/kotlin/parsers/MarkdownParser.kt b/plugins/base/src/main/kotlin/parsers/MarkdownParser.kt
index 8422d3be..53ab6bde 100644
--- a/plugins/base/src/main/kotlin/parsers/MarkdownParser.kt
+++ b/plugins/base/src/main/kotlin/parsers/MarkdownParser.kt
@@ -280,11 +280,13 @@ class MarkdownParser(
                 MarkdownElementTypes.IMAGE -> imagesHandler(node)
                 MarkdownTokenTypes.HARD_LINE_BREAK -> DocTagsFromIElementFactory.getInstance(node.type)
                 MarkdownTokenTypes.CODE_FENCE_CONTENT,
-                MarkdownTokenTypes.CODE_LINE,
+                MarkdownTokenTypes.CODE_LINE -> DocTagsFromIElementFactory.getInstance(
+                    MarkdownTokenTypes.TEXT,
+                    body = text.substring(node.startOffset, node.endOffset)
+                )
                 MarkdownTokenTypes.TEXT -> DocTagsFromIElementFactory.getInstance(
                     MarkdownTokenTypes.TEXT,
-                    body = text
-                        .substring(node.startOffset, node.endOffset).transform()
+                    body = text.substring(node.startOffset, node.endOffset).transform()
                 )
                 MarkdownElementTypes.MARKDOWN_FILE -> if (node.children.size == 1) visitNode(node.children.first()) else defaultHandler(
                     node
@@ -339,11 +341,12 @@ class MarkdownParser(
                     children += this[index]
                 } else {
                     val startOffset = this[index].startOffset
+                    val type = this[index].type
                     while (index < this.lastIndex) {
                         if (this.isNotLeaf(index + 1) || this[index + 1].startOffset != this[index].endOffset) {
                             val endOffset = this[index].endOffset
                             if (text.substring(startOffset, endOffset).transform().trim().isNotEmpty())
-                                children += LeafASTNode(MarkdownTokenTypes.TEXT, startOffset, endOffset)
+                                children += LeafASTNode(type, startOffset, endOffset)
                             break
                         }
                         index++
@@ -351,7 +354,7 @@ class MarkdownParser(
                     if (index == this.lastIndex) {
                         val endOffset = this[index].endOffset
                         if (text.substring(startOffset, endOffset).transform().trim().isNotEmpty())
-                            children += LeafASTNode(MarkdownTokenTypes.TEXT, startOffset, endOffset)
+                            children += LeafASTNode(type, startOffset, endOffset)
                     }
                 }
                 index++
diff --git a/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt b/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt
index 0118dcfd..878432b4 100644
--- a/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt
+++ b/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt
@@ -604,7 +604,9 @@ open class HtmlRenderer(
         div("sample-container") {
             code(code.style.joinToString(" ") { it.toString().toLowerCase() }) {
                 attributes["theme"] = "idea"
-                code.children.forEach { buildContentNode(it, pageContext) }
+                pre {
+                    code.children.forEach { buildContentNode(it, pageContext) }
+                }
             }
         }
     }
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 0c88b3c6..51ab0858 100644
--- a/plugins/base/src/main/kotlin/transformers/pages/comments/DocTagToContentConverter.kt
+++ b/plugins/base/src/main/kotlin/transformers/pages/comments/DocTagToContentConverter.kt
@@ -102,7 +102,7 @@ object DocTagToContentConverter : CommentsToContentConverter {
                     styles
                 )
             )
-            is BlockQuote -> listOf(
+            is BlockQuote, is Pre, is CodeBlock -> listOf(
                 ContentCodeBlock(
                     buildChildren(docTag),
                     "",
@@ -120,15 +120,6 @@ object DocTagToContentConverter : CommentsToContentConverter {
                     styles
                 )
             )
-            is CodeBlock -> listOf(
-                ContentCodeBlock(
-                    buildChildren(docTag),
-                    "",
-                    dci,
-                    sourceSets.toDisplaySourceSets(),
-                    styles
-                )
-            )
             is Img -> listOf(
                 ContentEmbeddedResource(
                     address = docTag.params["href"]!!,
diff --git a/plugins/base/src/main/kotlin/translators/psi/JavadocParser.kt b/plugins/base/src/main/kotlin/translators/psi/JavadocParser.kt
index 8262b3c6..b9c328dc 100644
--- a/plugins/base/src/main/kotlin/translators/psi/JavadocParser.kt
+++ b/plugins/base/src/main/kotlin/translators/psi/JavadocParser.kt
@@ -151,7 +151,7 @@ class JavadocParser(
             is PsiInlineDocTag -> convertInlineDocTag(this)
             is PsiDocParamRef -> toDocumentationLinkString()
             is PsiDocTagValue,
-            is LeafPsiElement -> (if ((prevSibling as? PsiDocToken)?.isLeadingAsterisk() == true) text?.trim() else text)?.takeUnless { it.isBlank() }
+            is LeafPsiElement -> text
             else -> null
         }
 
@@ -190,8 +190,8 @@ class JavadocParser(
             }
         }
 
-        private fun createBlock(element: Element): DocTag? {
-            val children = element.childNodes().mapNotNull { convertHtmlNode(it) }
+        private fun createBlock(element: Element, insidePre: Boolean = false): DocTag? {
+            val children = element.childNodes().mapNotNull { convertHtmlNode(it, insidePre = insidePre || element.tagName() == "pre") }
             fun ifChildrenPresent(operation: () -> DocTag): DocTag? {
                 return if (children.isNotEmpty()) operation() else null
             }
@@ -203,11 +203,7 @@ class JavadocParser(
                 "index" -> Index(children)
                 "i" -> ifChildrenPresent { I(children) }
                 "em" -> Em(children)
-                "code" -> ifChildrenPresent {
-                    if (element.hasAttr("data-inline")) CodeInline(children) else CodeBlock(
-                        children
-                    )
-                }
+                "code" -> ifChildrenPresent { CodeInline(children) }
                 "pre" -> Pre(children)
                 "ul" -> ifChildrenPresent { Ul(children) }
                 "ol" -> ifChildrenPresent { Ol(children) }
@@ -224,7 +220,7 @@ class JavadocParser(
         }
 
         override fun invoke(elements: Iterable<PsiElement>, asParagraph: Boolean): List<DocTag> =
-            Jsoup.parseBodyFragment(elements.mapNotNull { it.stringify() }.joinToString(" ", prefix = if (asParagraph) "<p>" else ""))
+            Jsoup.parseBodyFragment(elements.mapNotNull { it.stringify() }.joinToString("\n", prefix = if (asParagraph) "<p>" else ""))
                 .body().childNodes().mapNotNull { convertHtmlNode(it) }
     }
 
diff --git a/plugins/base/src/test/kotlin/translators/DefaultDescriptorToDocumentableTranslatorTest.kt b/plugins/base/src/test/kotlin/translators/DefaultDescriptorToDocumentableTranslatorTest.kt
index b0754429..8a8af626 100644
--- a/plugins/base/src/test/kotlin/translators/DefaultDescriptorToDocumentableTranslatorTest.kt
+++ b/plugins/base/src/test/kotlin/translators/DefaultDescriptorToDocumentableTranslatorTest.kt
@@ -1,21 +1,23 @@
 package translators
 
+import org.junit.jupiter.api.Assertions.*
+import org.jetbrains.dokka.model.doc.CodeBlock
+import org.jetbrains.dokka.model.doc.P
+import org.jetbrains.dokka.model.doc.Text
 import org.jetbrains.dokka.testApi.testRunner.AbstractCoreTest
-import org.junit.jupiter.api.Assertions
 import org.junit.jupiter.api.Test
 
 class DefaultDescriptorToDocumentableTranslatorTest : AbstractCoreTest() {
-
-    @Test
-    fun `data class kdocs over generated methods`() {
-        val configuration = dokkaConfiguration {
-            sourceSets {
-                sourceSet {
-                    sourceRoots = listOf("src/main/kotlin")
-                }
+    val configuration = dokkaConfiguration {
+        sourceSets {
+            sourceSet {
+                sourceRoots = listOf("src/main/kotlin")
             }
         }
+    }
 
+    @Test
+    fun `data class kdocs over generated methods`() {
         testInline(
             """
             |/src/main/kotlin/sample/XD.kt
@@ -39,7 +41,12 @@ class DefaultDescriptorToDocumentableTranslatorTest : AbstractCoreTest() {
         ) {
             documentablesMergingStage = { module ->
                 assert(module.documentationOf("XD", "copy") == "")
-                assert(module.documentationOf("XD", "equals") == "Memory is not what the heart desires. That is only a mirror.")
+                assert(
+                    module.documentationOf(
+                        "XD",
+                        "equals"
+                    ) == "Memory is not what the heart desires. That is only a mirror."
+                )
                 assert(module.documentationOf("XD", "hashCode") == "")
                 assert(module.documentationOf("XD", "toString") == "")
                 assert(module.documentationOf("XD", "custom") == "But the fat Hobbit, he knows. Eyes always watching.")
@@ -49,14 +56,6 @@ class DefaultDescriptorToDocumentableTranslatorTest : AbstractCoreTest() {
 
     @Test
     fun `simple class kdocs`() {
-        val configuration = dokkaConfiguration {
-            sourceSets {
-                sourceSet {
-                    sourceRoots = listOf("src/main/kotlin")
-                }
-            }
-        }
-
         testInline(
             """
             |/src/main/kotlin/sample/XD.kt
@@ -80,7 +79,71 @@ class DefaultDescriptorToDocumentableTranslatorTest : AbstractCoreTest() {
         ) {
             documentablesMergingStage = { module ->
                 assert(module.documentationOf("XD", "custom") == "But the fat Hobbit, he knows. Eyes always watching.")
-                assert(module.documentationOf("XD", "equals") == "Memory is not what the heart desires. That is only a mirror.")
+                assert(
+                    module.documentationOf(
+                        "XD",
+                        "equals"
+                    ) == "Memory is not what the heart desires. That is only a mirror."
+                )
+            }
+        }
+    }
+
+    @Test
+    fun `kdocs with code block`() {
+        testInline(
+            """
+            |/src/main/kotlin/sample/TestForCodeInDocs.kt
+            |package sample
+            |/**
+            | * Utility for building a String that represents an XML document.
+            | * The XmlBlob object is immutable and the passed values are copied where it makes sense.
+            | *
+            | * Note the XML Declaration is not output as part of the XmlBlob
+            | *
+            | * 
+            | *    val soapAttrs = attrs("soap-env" to "http://www.w3.org/2001/12/soap-envelope",
+            | *        "soap-env:encodingStyle" to "http://www.w3.org/2001/12/soap-encoding")
+            | *    val soapXml = node("soap-env:Envelope", soapAttrs,
+            | *        node("soap-env:Body", attrs("xmlns:m" to "http://example"),
+            | *            node("m:GetExample",
+            | *                node("m:GetExampleName", "BasePair")
+            | *            )
+            | *        )
+            | *    )
+            | *
+            | *
+            | */
+            |class TestForCodeInDocs {
+            |}
+        """.trimIndent(), configuration
+        ) {
+            documentablesMergingStage = { module ->
+                val description = module.descriptionOf("TestForCodeInDocs")
+                val expected = listOf(
+                    P(
+                        children = listOf(Text("Utility for building a String that represents an XML document. The XmlBlob object is immutable and the passed values are copied where it makes sense."))
+                    ),
+                    P(
+                        children = listOf(Text("Note the XML Declaration is not output as part of the XmlBlob"))
+                    ),
+                    CodeBlock(
+                        children = listOf(
+                            Text(
+                                """    val soapAttrs = attrs("soap-env" to "http://www.w3.org/2001/12/soap-envelope",
+        "soap-env:encodingStyle" to "http://www.w3.org/2001/12/soap-encoding")
+    val soapXml = node("soap-env:Envelope", soapAttrs,
+        node("soap-env:Body", attrs("xmlns:m" to "http://example"),
+            node("m:GetExample",
+                node("m:GetExampleName", "BasePair")
+            )
+        )
+    )"""
+                            )
+                        )
+                    )
+                )
+                assertEquals(expected, description?.root?.children)
             }
         }
     }
diff --git a/plugins/base/src/test/kotlin/translators/JavadocParserTest.kt b/plugins/base/src/test/kotlin/translators/JavadocParserTest.kt
index a1fbb2a0..8ffcfb3c 100644
--- a/plugins/base/src/test/kotlin/translators/JavadocParserTest.kt
+++ b/plugins/base/src/test/kotlin/translators/JavadocParserTest.kt
@@ -6,7 +6,6 @@ import org.jetbrains.dokka.model.childrenOfType
 import org.jetbrains.dokka.model.doc.*
 import org.jetbrains.dokka.model.firstChildOfType
 import org.jetbrains.dokka.testApi.testRunner.AbstractCoreTest
-import org.junit.jupiter.api.Assertions
 import org.junit.jupiter.api.Test
 import org.junit.jupiter.api.Assertions.*
 import utils.text
@@ -100,6 +99,15 @@ class JavadocParserTest : AbstractCoreTest() {
             | *     minute, but this specification follows the date and time conventions
             | *     for ISO C.
             | * </ul>
+            | * <pre class="prettyprint">
+            | * &lt;androidx.fragment.app.FragmentContainerView
+            | *        xmlns:android="http://schemas.android.com/apk/res/android"
+            | *        xmlns:app="http://schemas.android.com/apk/res-auto"
+            | *        android:id="@+id/fragment_container_view"
+            | *        android:layout_width="match_parent"
+            | *        android:layout_height="match_parent"&gt;
+            | * &lt;/androidx.fragment.app.FragmentContainerView&gt;
+            | * </pre>
             | * <p>
             | * In all cases, arguments given to methods for these purposes need
             | * not fall within the indicated ranges; for example, a date may be
@@ -153,4 +161,20 @@ class JavadocParserTest : AbstractCoreTest() {
             assertEquals("java.util.Calendar", sees[1].name)
         }
     }
+
+    @Test
+    fun `correctly parsed code block`(){
+        performJavadocTest { module ->
+            val dateDescription = module.descriptionOf("Date2")!!
+            val preTagContent = dateDescription.firstChildOfType<Pre>().firstChildOfType<Text>()
+            val expectedText = """<androidx.fragment.app.FragmentContainerView
+        xmlns:android="http://schemas.android.com/apk/res/android"
+        xmlns:app="http://schemas.android.com/apk/res-auto"
+        android:id="@+id/fragment_container_view"
+        android:layout_width="match_parent"
+        android:layout_height="match_parent">
+ </androidx.fragment.app.FragmentContainerView>""".trimIndent()
+            assertEquals(expectedText.trim(), preTagContent.body.trim())
+        }
+    }
 }
diff --git a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/JavadocContentToHtmlTranslator.kt b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/JavadocContentToHtmlTranslator.kt
index 413b6387..7f179f75 100644
--- a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/JavadocContentToHtmlTranslator.kt
+++ b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/JavadocContentToHtmlTranslator.kt
@@ -20,7 +20,7 @@ internal class JavadocContentToHtmlTranslator(
             is ContentText -> htmlForText(node)
             is ContentDRILink -> buildLinkFromNode(node, relative)
             is ContentResolvedLink -> buildLinkFromNode(node, relative)
-            is ContentCode -> htmlForCode(node.children, relative)
+            is ContentCode -> htmlForCode(node, relative)
             is ContentList -> htmlForList(node.children, relative)
             is JavadocSignatureContentNode -> htmlForSignature(node, relative)
             is ContentBreakLine -> "<br>"
@@ -44,16 +44,17 @@ internal class JavadocContentToHtmlTranslator(
     private fun htmlForParagraph(nodes: List<ContentNode>, relative: PageNode?) =
         "<p>${htmlForContentNodes(nodes, relative)}</p>"
 
-    private fun htmlForCode(code: List<ContentNode>, relative: PageNode?): String {
-        fun nodeToText(node: ContentNode): String = when (node) {
-            is ContentText -> node.text
-            is ContentBreakLine -> ""
+    private fun htmlForCode(code: ContentCode, relative: PageNode?): String {
+        fun nodeToText(node: ContentNode, insidePre: Boolean = false): String = when (node) {
+            is ContentText -> node.text.htmlEscape()
+            is ContentBreakLine -> if(insidePre) "\n" else "<br>"
             is ContentDRILink -> buildLinkFromNode(node, relative)
             is ContentResolvedLink -> buildLinkFromNode(node, relative)
-            is ContentCode -> node.children.joinToString("") { nodeToText(it) }
+            is ContentCodeBlock -> "<pre><code>${node.children.joinToString("") { nodeToText(it, insidePre = true) }}</code></pre>"
+            is ContentCodeInline -> "<code>${node.children.joinToString("") { nodeToText(it) }}</code>"
             else -> run { context.logger.error("Cannot cast $node as ContentText!"); "" }
         }
-        return code.map(::nodeToText).joinToString("<br>", """<code>""", "</code>") { it }
+        return nodeToText(code)
     }
 
     private fun htmlForList(elements: List<ContentNode>, relative: PageNode?) =