Add the ability to pretty print DokkaConfiguration (#2872)

9 files changed, 137 insertions, 24 deletions

diff --git a/core/api/core.api b/core/api/core.api
index a6f6fd4a..f51d7043 100644
--- a/core/api/core.api
+++ b/core/api/core.api
@@ -1,14 +1,21 @@
-public final class org/jetbrains/dokka/ConfigurationKt {
+public final class org/jetbrains/dokka/ConfigurationJsonUtilsKt {
 	public static final fun DokkaConfigurationImpl (Ljava/lang/String;)Lorg/jetbrains/dokka/DokkaConfigurationImpl;
+	public static final fun GlobalDokkaConfiguration (Ljava/lang/String;)Lorg/jetbrains/dokka/GlobalDokkaConfiguration;
+	public static final fun toCompactJsonString (Lorg/jetbrains/dokka/DokkaConfiguration;)Ljava/lang/String;
+	public static final fun toCompactJsonString (Lorg/jetbrains/dokka/plugability/ConfigurableBlock;)Ljava/lang/String;
+	public static final fun toJsonString (Lorg/jetbrains/dokka/DokkaConfiguration;)Ljava/lang/String;
+	public static final fun toJsonString (Lorg/jetbrains/dokka/plugability/ConfigurableBlock;)Ljava/lang/String;
+	public static final fun toPrettyJsonString (Lorg/jetbrains/dokka/DokkaConfiguration;)Ljava/lang/String;
+	public static final fun toPrettyJsonString (Lorg/jetbrains/dokka/plugability/ConfigurableBlock;)Ljava/lang/String;
+}
+
+public final class org/jetbrains/dokka/ConfigurationKt {
 	public static final fun ExternalDocumentationLink (Ljava/lang/String;Ljava/lang/String;)Lorg/jetbrains/dokka/ExternalDocumentationLinkImpl;
 	public static final fun ExternalDocumentationLink (Ljava/net/URL;Ljava/net/URL;)Lorg/jetbrains/dokka/ExternalDocumentationLinkImpl;
 	public static synthetic fun ExternalDocumentationLink$default (Ljava/lang/String;Ljava/lang/String;ILjava/lang/Object;)Lorg/jetbrains/dokka/ExternalDocumentationLinkImpl;
 	public static synthetic fun ExternalDocumentationLink$default (Ljava/net/URL;Ljava/net/URL;ILjava/lang/Object;)Lorg/jetbrains/dokka/ExternalDocumentationLinkImpl;
-	public static final fun GlobalDokkaConfiguration (Ljava/lang/String;)Lorg/jetbrains/dokka/GlobalDokkaConfiguration;
 	public static final fun apply (Lorg/jetbrains/dokka/DokkaConfiguration;Lorg/jetbrains/dokka/GlobalDokkaConfiguration;)Lorg/jetbrains/dokka/DokkaConfiguration;
 	public static final fun build (Ljava/lang/Iterable;)Ljava/util/List;
-	public static final fun toJsonString (Lorg/jetbrains/dokka/DokkaConfiguration;)Ljava/lang/String;
-	public static final fun toJsonString (Lorg/jetbrains/dokka/plugability/ConfigurableBlock;)Ljava/lang/String;
 }
 
 public final class org/jetbrains/dokka/CoreExtensions {
diff --git a/core/src/main/kotlin/ConfigurationJsonUtils.kt b/core/src/main/kotlin/ConfigurationJsonUtils.kt
new file mode 100644
index 00000000..62c1cc8c
--- /dev/null
+++ b/core/src/main/kotlin/ConfigurationJsonUtils.kt
@@ -0,0 +1,50 @@
+package org.jetbrains.dokka
+
+import org.jetbrains.dokka.plugability.ConfigurableBlock
+import org.jetbrains.dokka.utilities.parseJson
+import org.jetbrains.dokka.utilities.serializeAsCompactJson
+import org.jetbrains.dokka.utilities.serializeAsPrettyJson
+
+fun DokkaConfigurationImpl(json: String): DokkaConfigurationImpl = parseJson(json)
+
+fun GlobalDokkaConfiguration(json: String): GlobalDokkaConfiguration = parseJson(json)
+
+@Deprecated("Renamed to better distinguish between compact/pretty prints", ReplaceWith("this.toCompactJsonString()"))
+fun DokkaConfiguration.toJsonString(): String = this.toCompactJsonString()
+
+@Deprecated("Renamed to better distinguish between compact/pretty prints", ReplaceWith("this.toCompactJsonString()"))
+fun <T : ConfigurableBlock> T.toJsonString(): String = this.toCompactJsonString()
+
+/**
+ * Serializes [DokkaConfiguration] as a machine-readable and compact JSON string.
+ *
+ * The returned string is not very human friendly as it will be difficult to parse by eyes due to it
+ * being compact and in one line. If you want to show the output to a human being, see [toPrettyJsonString].
+ */
+fun DokkaConfiguration.toCompactJsonString(): String = serializeAsCompactJson(this)
+
+/**
+ * Serializes [DokkaConfiguration] as a human-readable (pretty printed) JSON string.
+ *
+ * The returned string will have excessive line breaks and indents, which might not be
+ * desirable when passing this value between API consumers/producers. If you want
+ * a machine-readable and compact json string, see [toCompactJsonString].
+ */
+fun DokkaConfiguration.toPrettyJsonString(): String = serializeAsPrettyJson(this)
+
+/**
+ * Serializes a [ConfigurableBlock] as a machine-readable and compact JSON string.
+ *
+ * The returned string is not very human friendly as it will be difficult to parse by eyes due to it
+ * being compact and in one line. If you want to show the output to a human being, see [toPrettyJsonString].
+ */
+fun <T : ConfigurableBlock> T.toCompactJsonString(): String = serializeAsCompactJson(this)
+
+/**
+ * Serializes a [ConfigurableBlock] as a human-readable (pretty printed) JSON string.
+ *
+ * The returned string will have excessive line breaks and indents, which might not be
+ * desirable when passing this value between API consumers/producers. If you want
+ * a machine-readable and compact json string, see [toCompactJsonString].
+ */
+fun <T : ConfigurableBlock> T.toPrettyJsonString(): String = serializeAsCompactJson(this)
diff --git a/core/src/main/kotlin/configuration.kt b/core/src/main/kotlin/configuration.kt
index 71356e67..9bb81318 100644
--- a/core/src/main/kotlin/configuration.kt
+++ b/core/src/main/kotlin/configuration.kt
@@ -2,10 +2,7 @@
 
 package org.jetbrains.dokka
 
-import org.jetbrains.dokka.plugability.ConfigurableBlock
 import org.jetbrains.dokka.utilities.cast
-import org.jetbrains.dokka.utilities.parseJson
-import org.jetbrains.dokka.utilities.toJsonString
 import java.io.File
 import java.io.Serializable
 import java.net.URL
@@ -95,8 +92,6 @@ data class DokkaSourceSetID(
     }
 }
 
-fun DokkaConfigurationImpl(json: String): DokkaConfigurationImpl = parseJson(json)
-
 /**
  * Global options can be configured and applied to all packages and modules at once, overwriting package configuration.
  *
@@ -111,8 +106,6 @@ data class GlobalDokkaConfiguration(
     val sourceLinks: List<SourceLinkDefinitionImpl>?
 )
 
-fun GlobalDokkaConfiguration(json: String): GlobalDokkaConfiguration = parseJson(json)
-
 fun DokkaConfiguration.apply(globals: GlobalDokkaConfiguration): DokkaConfiguration = this.apply {
     sourceSets.forEach {
         it.perPackageOptions.cast<MutableList<DokkaConfiguration.PackageOptions>>().addAll(globals.perPackageOptions ?: emptyList())
@@ -127,9 +120,6 @@ fun DokkaConfiguration.apply(globals: GlobalDokkaConfiguration): DokkaConfigurat
     }
 }
 
-fun DokkaConfiguration.toJsonString(): String = toJsonString(this)
-fun <T : ConfigurableBlock> T.toJsonString(): String = toJsonString(this)
-
 interface DokkaConfiguration : Serializable {
     val moduleName: String
     val moduleVersion: String?
diff --git a/core/src/main/kotlin/utilities/json.kt b/core/src/main/kotlin/utilities/json.kt
index d3762f6d..61736a99 100644
--- a/core/src/main/kotlin/utilities/json.kt
+++ b/core/src/main/kotlin/utilities/json.kt
@@ -28,8 +28,21 @@ internal class TypeReference<T> private constructor(
     }
 }
 
+// not used anywhere since at least 1.7.20, but might still be referenced in previously compiled
+// inline functions. should be safe to remove after a few major releases.
 @PublishedApi
-internal fun toJsonString(value: Any): String = objectMapper.writeValueAsString(value)
+@Deprecated(
+    "Left for previously compiled public inline classes, not for use",
+    ReplaceWith("serializeAsCompactJson(value)"),
+    level = DeprecationLevel.ERROR
+)
+internal fun toJsonString(value: Any): String = serializeAsCompactJson(value)
+
+internal fun serializeAsCompactJson(value: Any): String =
+    objectMapper.writeValueAsString(value)
+
+internal fun serializeAsPrettyJson(value: Any): String =
+    objectMapper.writerWithDefaultPrettyPrinter().writeValueAsString(value)
 
 @PublishedApi
 internal inline fun <reified T : Any> parseJson(json: String): T = parseJson(json, TypeReference())
diff --git a/core/src/test/kotlin/utilities/DokkaConfigurationJsonTest.kt b/core/src/test/kotlin/utilities/DokkaConfigurationJsonTest.kt
index ba33ab92..9ac5fea0 100644
--- a/core/src/test/kotlin/utilities/DokkaConfigurationJsonTest.kt
+++ b/core/src/test/kotlin/utilities/DokkaConfigurationJsonTest.kt
@@ -20,7 +20,7 @@ class DokkaConfigurationJsonTest {
             )
         )
 
-        val jsonString = configuration.toJsonString()
+        val jsonString = configuration.toCompactJsonString()
         val parsedConfiguration = DokkaConfigurationImpl(jsonString)
         assertEquals(configuration, parsedConfiguration)
     }
diff --git a/core/src/test/kotlin/utilities/JsonKtTest.kt b/core/src/test/kotlin/utilities/JsonKtTest.kt
new file mode 100644
index 00000000..ee78392c
--- /dev/null
+++ b/core/src/test/kotlin/utilities/JsonKtTest.kt
@@ -0,0 +1,57 @@
+package utilities
+
+import org.jetbrains.dokka.utilities.serializeAsCompactJson
+import org.jetbrains.dokka.utilities.serializeAsPrettyJson
+import kotlin.test.assertEquals
+import kotlin.test.Test
+
+class JsonTest {
+
+    @Test
+    fun `should serialize an object as compact json`() {
+        val testObject = SimpleTestDataClass(
+            someString = "Foo",
+            someInt = 42,
+            someDouble = 42.0
+        )
+
+        val actual = serializeAsCompactJson(testObject)
+        val expected = "{\"someString\":\"Foo\",\"someInt\":42,\"someIntWithDefaultValue\":42,\"someDouble\":42.0}"
+
+        assertEquals(expected, actual)
+    }
+
+    @Test
+    fun `should serialize an object as pretty json`() {
+        val testObject = SimpleTestDataClass(
+            someString = "Foo",
+            someInt = 42,
+            someDouble = 42.0
+        )
+
+        val actual = serializeAsPrettyJson(testObject)
+
+        val expected = """
+            {
+              "someString" : "Foo",
+              "someInt" : 42,
+              "someIntWithDefaultValue" : 42,
+              "someDouble" : 42.0
+            }""".trimIndent().withSystemLineSeparator()
+
+        assertEquals(expected, actual)
+    }
+
+    /**
+     * If the expected output was generated on Linux, but the tests are run under Windows,
+     * the test might fail when comparing the strings due to different separators.
+     */
+    private fun String.withSystemLineSeparator(): String = this.replace("\n", System.lineSeparator())
+}
+
+data class SimpleTestDataClass(
+    val someString: String,
+    val someInt: Int,
+    val someIntWithDefaultValue: Int = 42,
+    val someDouble: Double
+)
diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/AbstractDokkaTask.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/AbstractDokkaTask.kt
index dbd86fac..d7ddfc93 100644
--- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/AbstractDokkaTask.kt
+++ b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/AbstractDokkaTask.kt
@@ -182,7 +182,7 @@ abstract class AbstractDokkaTask : DefaultTask() {
         val pluginConfiguration = PluginConfigurationImpl(
             fqPluginName = P::class.qualifiedName!!,
             serializationFormat = DokkaConfiguration.SerializationFormat.JSON,
-            values = instance.toJsonString()
+            values = instance.toCompactJsonString()
         )
         pluginsConfiguration.add(pluginConfiguration)
     }
@@ -200,7 +200,7 @@ abstract class AbstractDokkaTask : DefaultTask() {
     @TaskAction
     internal open fun generateDocumentation() {
         DokkaBootstrap(runtime, DokkaBootstrapImpl::class).apply {
-            configure(buildDokkaConfiguration().toJsonString(), createProxyLogger())
+            configure(buildDokkaConfiguration().toCompactJsonString(), createProxyLogger())
             /**
              * Run in a new thread to avoid memory leaks that are related to ThreadLocal (that keeps `URLCLassLoader`)
              * Currently, all `ThreadLocal`s leaking are in the compiler/IDE codebase.
diff --git a/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaConfigurationJsonTest.kt b/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaConfigurationJsonTest.kt
index a598284f..64aa1334 100644
--- a/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaConfigurationJsonTest.kt
+++ b/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaConfigurationJsonTest.kt
@@ -2,10 +2,7 @@ package org.jetbrains.dokka.gradle
 
 import org.gradle.kotlin.dsl.withType
 import org.gradle.testfixtures.ProjectBuilder
-import org.jetbrains.dokka.DokkaConfiguration
-import org.jetbrains.dokka.DokkaConfigurationImpl
-import org.jetbrains.dokka.PluginConfigurationImpl
-import org.jetbrains.dokka.toJsonString
+import org.jetbrains.dokka.*
 import java.io.File
 import java.net.URL
 import kotlin.test.Test
@@ -50,7 +47,7 @@ class DokkaConfigurationJsonTest {
         }
 
         val sourceConfiguration = dokkaTask.buildDokkaConfiguration()
-        val configurationJson = sourceConfiguration.toJsonString()
+        val configurationJson = sourceConfiguration.toCompactJsonString()
         val parsedConfiguration = DokkaConfigurationImpl(configurationJson)
 
         assertEquals(sourceConfiguration, parsedConfiguration)
diff --git a/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaConfigurationSerializableTest.kt b/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaConfigurationSerializableTest.kt
index 3ef1ed74..ac8f040e 100644
--- a/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaConfigurationSerializableTest.kt
+++ b/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaConfigurationSerializableTest.kt
@@ -4,7 +4,6 @@ import org.gradle.kotlin.dsl.withType
 import org.gradle.testfixtures.ProjectBuilder
 import org.jetbrains.dokka.DokkaConfiguration
 import org.jetbrains.dokka.PluginConfigurationImpl
-import org.jetbrains.dokka.toJsonString
 import org.junit.Rule
 import org.junit.rules.TemporaryFolder
 import java.io.File