Add the ability to pretty print DokkaConfiguration (#2872)

5 files changed, 122 insertions, 12 deletions

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
+)