From 3fb60bc74a4ed4e4c795f2f14fa112321a3c94cc Mon Sep 17 00:00:00 2001
From: Don Cross <cosinekitty@users.noreply.github.com>
Date: Wed, 4 May 2022 12:33:21 -0400
Subject: [PATCH] Support code blocks and inline code for GFM format (#2485)

Fixes #2477.

Inline code, text that is nested within a pair of backquotes,
is now converted into GitHub Flavored Markdown (gfm) without
stripping out the backquotes. For example:

    The parameter `sum` must be a non-negative real number.

Code blocks, which are any number of lines of literal text
between triple-backquotes, and an optional programming language
name, are now preserved. If absent, the programming language
is assumed to be "kotlin". This follows the behavior of the
html renderer. For example:

    Here is an example of calling the function:
    ```kotlin
    val sum = addThemUp(left, right)
    ```
---
 plugins/base/api/base.api                     |  4 ++
 .../documentables/PageContentBuilder.kt       | 36 ++++++++++++++
 plugins/gfm/api/gfm.api                       |  4 ++
 .../dokka/gfm/renderer/CommonmarkRenderer.kt  | 16 +++++++
 .../kotlin/renderers/gfm/CodeWrappingTest.kt  | 48 +++++++++++++++++++
 5 files changed, 108 insertions(+)
 create mode 100644 plugins/gfm/src/test/kotlin/renderers/gfm/CodeWrappingTest.kt

diff --git a/plugins/base/api/base.api b/plugins/base/api/base.api
index 101a00e9ce..4b68b3d7b9 100644
--- a/plugins/base/api/base.api
+++ b/plugins/base/api/base.api
@@ -1503,6 +1503,10 @@ public class org/jetbrains/dokka/base/translators/documentables/PageContentBuild
 	public final fun buildGroup (Ljava/util/Set;Ljava/util/Set;Lorg/jetbrains/dokka/pages/Kind;Ljava/util/Set;Lorg/jetbrains/dokka/model/properties/PropertyContainer;Lkotlin/jvm/functions/Function1;)Lorg/jetbrains/dokka/pages/ContentGroup;
 	public static synthetic fun buildGroup$default (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Ljava/util/Set;Ljava/util/Set;Lorg/jetbrains/dokka/pages/Kind;Ljava/util/Set;Lorg/jetbrains/dokka/model/properties/PropertyContainer;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lorg/jetbrains/dokka/pages/ContentGroup;
 	public final fun buildSignature (Lorg/jetbrains/dokka/model/Documentable;)Ljava/util/List;
+	public final fun codeBlock (Ljava/lang/String;Lorg/jetbrains/dokka/pages/Kind;Ljava/util/Set;Ljava/util/Set;Lorg/jetbrains/dokka/model/properties/PropertyContainer;Lkotlin/jvm/functions/Function1;)V
+	public static synthetic fun codeBlock$default (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Ljava/lang/String;Lorg/jetbrains/dokka/pages/Kind;Ljava/util/Set;Ljava/util/Set;Lorg/jetbrains/dokka/model/properties/PropertyContainer;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)V
+	public final fun codeInline (Ljava/lang/String;Lorg/jetbrains/dokka/pages/Kind;Ljava/util/Set;Ljava/util/Set;Lorg/jetbrains/dokka/model/properties/PropertyContainer;Lkotlin/jvm/functions/Function1;)V
+	public static synthetic fun codeInline$default (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Ljava/lang/String;Lorg/jetbrains/dokka/pages/Kind;Ljava/util/Set;Ljava/util/Set;Lorg/jetbrains/dokka/model/properties/PropertyContainer;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)V
 	public final fun comment (Lorg/jetbrains/dokka/model/doc/DocTag;Lorg/jetbrains/dokka/pages/Kind;Ljava/util/Set;Ljava/util/Set;Lorg/jetbrains/dokka/model/properties/PropertyContainer;)V
 	public static synthetic fun comment$default (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/model/doc/DocTag;Lorg/jetbrains/dokka/pages/Kind;Ljava/util/Set;Ljava/util/Set;Lorg/jetbrains/dokka/model/properties/PropertyContainer;ILjava/lang/Object;)V
 	public final fun constant (Ljava/lang/String;)V
diff --git a/plugins/base/src/main/kotlin/translators/documentables/PageContentBuilder.kt b/plugins/base/src/main/kotlin/translators/documentables/PageContentBuilder.kt
index 7b6fbc7a39..363b6a3ff2 100644
--- a/plugins/base/src/main/kotlin/translators/documentables/PageContentBuilder.kt
+++ b/plugins/base/src/main/kotlin/translators/documentables/PageContentBuilder.kt
@@ -363,6 +363,42 @@ open class PageContentBuilder(
             contents += ContentGroup(content, DCI(mainDRI, kind), sourceSets.toDisplaySourceSets(), styles, extra)
         }
 
+        fun codeBlock(
+            language: String = "",
+            kind: Kind = ContentKind.Main,
+            sourceSets: Set<DokkaSourceSet> = mainSourcesetData,
+            styles: Set<Style> = mainStyles,
+            extra: PropertyContainer<ContentNode> = mainExtra,
+            block: DocumentableContentBuilder.() -> Unit
+        ) {
+            contents += ContentCodeBlock(
+                contentFor(mainDRI, sourceSets, kind, styles, extra, block).children,
+                language,
+                DCI(mainDRI, kind),
+                sourceSets.toDisplaySourceSets(),
+                styles,
+                extra
+            )
+        }
+
+        fun codeInline(
+            language: String,
+            kind: Kind = ContentKind.Main,
+            sourceSets: Set<DokkaSourceSet> = mainSourcesetData,
+            styles: Set<Style> = mainStyles,
+            extra: PropertyContainer<ContentNode> = mainExtra,
+            block: DocumentableContentBuilder.() -> Unit
+        ) {
+            contents += ContentCodeInline(
+                contentFor(mainDRI, sourceSets, kind, styles, extra, block).children,
+                language,
+                DCI(mainDRI, kind),
+                sourceSets.toDisplaySourceSets(),
+                styles,
+                extra
+            )
+        }
+
         fun firstParagraphComment(
             content: DocTag,
             kind: Kind = ContentKind.Comment,
diff --git a/plugins/gfm/api/gfm.api b/plugins/gfm/api/gfm.api
index ba189898cf..b697021103 100644
--- a/plugins/gfm/api/gfm.api
+++ b/plugins/gfm/api/gfm.api
@@ -41,6 +41,10 @@ public final class org/jetbrains/dokka/gfm/renderer/BriefCommentPreprocessor : o
 
 public class org/jetbrains/dokka/gfm/renderer/CommonmarkRenderer : org/jetbrains/dokka/base/renderers/DefaultRenderer {
 	public fun <init> (Lorg/jetbrains/dokka/plugability/DokkaContext;)V
+	public synthetic fun buildCodeBlock (Ljava/lang/Object;Lorg/jetbrains/dokka/pages/ContentCodeBlock;Lorg/jetbrains/dokka/pages/ContentPage;)V
+	public fun buildCodeBlock (Ljava/lang/StringBuilder;Lorg/jetbrains/dokka/pages/ContentCodeBlock;Lorg/jetbrains/dokka/pages/ContentPage;)V
+	public synthetic fun buildCodeInline (Ljava/lang/Object;Lorg/jetbrains/dokka/pages/ContentCodeInline;Lorg/jetbrains/dokka/pages/ContentPage;)V
+	public fun buildCodeInline (Ljava/lang/StringBuilder;Lorg/jetbrains/dokka/pages/ContentCodeInline;Lorg/jetbrains/dokka/pages/ContentPage;)V
 	public synthetic fun buildDRILink (Ljava/lang/Object;Lorg/jetbrains/dokka/pages/ContentDRILink;Lorg/jetbrains/dokka/pages/ContentPage;Ljava/util/Set;)V
 	public fun buildDRILink (Ljava/lang/StringBuilder;Lorg/jetbrains/dokka/pages/ContentDRILink;Lorg/jetbrains/dokka/pages/ContentPage;Ljava/util/Set;)V
 	public synthetic fun buildDivergent (Ljava/lang/Object;Lorg/jetbrains/dokka/pages/ContentDivergentGroup;Lorg/jetbrains/dokka/pages/ContentPage;)V
diff --git a/plugins/gfm/src/main/kotlin/org/jetbrains/dokka/gfm/renderer/CommonmarkRenderer.kt b/plugins/gfm/src/main/kotlin/org/jetbrains/dokka/gfm/renderer/CommonmarkRenderer.kt
index 133229441d..d192b9a637 100644
--- a/plugins/gfm/src/main/kotlin/org/jetbrains/dokka/gfm/renderer/CommonmarkRenderer.kt
+++ b/plugins/gfm/src/main/kotlin/org/jetbrains/dokka/gfm/renderer/CommonmarkRenderer.kt
@@ -311,6 +311,22 @@ open class CommonmarkRenderer(
         }
     }
 
+    override fun StringBuilder.buildCodeBlock(code: ContentCodeBlock, pageContext: ContentPage) {
+        append("```")
+        append(code.language.ifEmpty { "kotlin" })
+        buildNewLine()
+        code.children.forEach { it.build(this, pageContext) }
+        buildNewLine()
+        append("```")
+        buildNewLine()
+    }
+
+    override fun StringBuilder.buildCodeInline(code: ContentCodeInline, pageContext: ContentPage) {
+        append("`")
+        code.children.forEach { it.build(this, pageContext) }
+        append("`")
+    }
+
     private fun decorators(styles: Set<Style>) = buildString {
         styles.forEach {
             when (it) {
diff --git a/plugins/gfm/src/test/kotlin/renderers/gfm/CodeWrappingTest.kt b/plugins/gfm/src/test/kotlin/renderers/gfm/CodeWrappingTest.kt
new file mode 100644
index 0000000000..ce0c3d0c7f
--- /dev/null
+++ b/plugins/gfm/src/test/kotlin/renderers/gfm/CodeWrappingTest.kt
@@ -0,0 +1,48 @@
+package renderers.gfm
+
+import org.jetbrains.dokka.gfm.renderer.CommonmarkRenderer
+import org.jetbrains.dokka.pages.TextStyle
+import org.junit.jupiter.api.Test
+import kotlin.test.assertEquals
+import renderers.*
+
+class CodeWrappingTest : GfmRenderingOnlyTestBase() {
+    @Test
+    fun wrappedCodeBlock() {
+        val page = testPage {
+            codeBlock {
+                text("fun myCode(): String")
+            }
+        }
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |```kotlin
+                        |fun myCode(): String
+                        |```""".trimMargin()
+
+        CommonmarkRenderer(context).render(page)
+        assertEquals(expect, renderedContent)
+    }
+
+    @Test
+    fun wrappedInlineCode() {
+        val page = testPage {
+            text("This function adds the values of ")
+            codeInline("") { 
+                text("left") 
+            }
+            text(" and ")
+            codeInline("") {
+                text("right")
+            }
+            text(".\nBoth numbers must be finite, or an exception occurs.\n")
+        }
+        val expect = """|//[testPage](test-page.md)
+                        |
+                        |This function adds the values of `left` and `right`.
+                        |Both numbers must be finite, or an exception occurs.""".trimMargin()
+
+        CommonmarkRenderer(context).render(page)
+        assertEquals(expect, renderedContent)
+    }
+}