Add the ability to pretty print DokkaConfiguration (#2872)

3 files changed, 64 insertions, 11 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())