diff options
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 |