From 3fe3a934092cd844a6e0b691c87c367b9fc4d5b3 Mon Sep 17 00:00:00 2001 From: Kamil Doległo <9080183+kamildoleglo@users.noreply.github.com> Date: Wed, 25 Nov 2020 13:17:51 +0100 Subject: Remove suspend from SourceToDocumentableTranslator (#1622) * Remove suspend from SourceToDocumentableTranslator * Introduce AsyncSourceToDocumentableTranslator Co-authored-by: Marcin Aman --- core/src/main/kotlin/DokkaGenerator.kt | 8 ++++++-- .../sources/AsyncSourceToDocumentableTranslator.kt | 15 +++++++++++++++ .../sources/SourceToDocumentableTranslator.kt | 2 +- docs/src/doc/docs/developer_guide/extension_points.md | 8 ++++++++ .../DefaultDescriptorToDocumentableTranslator.kt | 5 +++-- .../translators/psi/DefaultPsiToDocumentableTranslator.kt | 5 +++-- 6 files changed, 36 insertions(+), 7 deletions(-) create mode 100644 core/src/main/kotlin/transformers/sources/AsyncSourceToDocumentableTranslator.kt diff --git a/core/src/main/kotlin/DokkaGenerator.kt b/core/src/main/kotlin/DokkaGenerator.kt index b6216bdb..b3d58439 100644 --- a/core/src/main/kotlin/DokkaGenerator.kt +++ b/core/src/main/kotlin/DokkaGenerator.kt @@ -10,6 +10,7 @@ import org.jetbrains.dokka.plugability.DokkaPlugin import org.jetbrains.dokka.utilities.DokkaLogger import org.jetbrains.dokka.utilities.report import kotlinx.coroutines.* +import org.jetbrains.dokka.transformers.sources.AsyncSourceToDocumentableTranslator import org.jetbrains.dokka.utilities.parallelMap @@ -149,8 +150,11 @@ class DokkaGenerator( } private suspend fun translateSources(sourceSet: DokkaSourceSet, context: DokkaContext) = - context[CoreExtensions.sourceToDocumentableTranslator].parallelMap { - it.invoke(sourceSet, context) + context[CoreExtensions.sourceToDocumentableTranslator].parallelMap { translator -> + when(translator){ + is AsyncSourceToDocumentableTranslator -> translator.invokeSuspending(sourceSet, context) + else -> translator.invoke(sourceSet, context) + } } } diff --git a/core/src/main/kotlin/transformers/sources/AsyncSourceToDocumentableTranslator.kt b/core/src/main/kotlin/transformers/sources/AsyncSourceToDocumentableTranslator.kt new file mode 100644 index 00000000..19113446 --- /dev/null +++ b/core/src/main/kotlin/transformers/sources/AsyncSourceToDocumentableTranslator.kt @@ -0,0 +1,15 @@ +package org.jetbrains.dokka.transformers.sources + +import kotlinx.coroutines.runBlocking +import org.jetbrains.dokka.DokkaConfiguration +import org.jetbrains.dokka.model.DModule +import org.jetbrains.dokka.plugability.DokkaContext + +interface AsyncSourceToDocumentableTranslator : SourceToDocumentableTranslator { + suspend fun invokeSuspending(sourceSet: DokkaConfiguration.DokkaSourceSet, context: DokkaContext): DModule + + override fun invoke(sourceSet: DokkaConfiguration.DokkaSourceSet, context: DokkaContext): DModule = + runBlocking { + invokeSuspending(sourceSet, context) + } +} \ No newline at end of file diff --git a/core/src/main/kotlin/transformers/sources/SourceToDocumentableTranslator.kt b/core/src/main/kotlin/transformers/sources/SourceToDocumentableTranslator.kt index 8ac59a15..2252dde3 100644 --- a/core/src/main/kotlin/transformers/sources/SourceToDocumentableTranslator.kt +++ b/core/src/main/kotlin/transformers/sources/SourceToDocumentableTranslator.kt @@ -5,5 +5,5 @@ import org.jetbrains.dokka.model.DModule import org.jetbrains.dokka.plugability.DokkaContext interface SourceToDocumentableTranslator { - suspend fun invoke(sourceSet: DokkaSourceSet, context: DokkaContext): DModule + fun invoke(sourceSet: DokkaSourceSet, context: DokkaContext): DModule } diff --git a/docs/src/doc/docs/developer_guide/extension_points.md b/docs/src/doc/docs/developer_guide/extension_points.md index b121c3f7..22272562 100644 --- a/docs/src/doc/docs/developer_guide/extension_points.md +++ b/docs/src/doc/docs/developer_guide/extension_points.md @@ -28,6 +28,14 @@ By default, two translators are created: After this step, all data from different source sets and languages are kept separately. +If you are using Kotlin it is recommended to make use of the asynchronous version, providing you implementation of `invokeSuspending`: + +```kotlin +interface AsyncSourceToDocumentableTranslator : SourceToDocumentableTranslator { + suspend fun invokeSuspending(sourceSet: DokkaConfiguration.DokkaSourceSet, context: DokkaContext): DModule +} +``` + ### Pre-merge documentation transform Here you can apply any transformation to model data before different source sets are merged. diff --git a/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt b/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt index 4695dac5..17cd493a 100644 --- a/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt +++ b/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt @@ -21,6 +21,7 @@ import org.jetbrains.dokka.plugability.DokkaContext import org.jetbrains.dokka.plugability.plugin import org.jetbrains.dokka.plugability.query import org.jetbrains.dokka.plugability.querySingle +import org.jetbrains.dokka.transformers.sources.AsyncSourceToDocumentableTranslator import org.jetbrains.dokka.transformers.sources.SourceToDocumentableTranslator import org.jetbrains.dokka.utilities.DokkaLogger import org.jetbrains.kotlin.builtins.functions.FunctionClassDescriptor @@ -65,11 +66,11 @@ import org.jetbrains.kotlin.resolve.constants.KClassValue as ConstantsKtClassVal class DefaultDescriptorToDocumentableTranslator( context: DokkaContext -) : SourceToDocumentableTranslator { +) : AsyncSourceToDocumentableTranslator { private val kotlinAnalysis: KotlinAnalysis = context.plugin().querySingle { kotlinAnalysis } - override suspend fun invoke(sourceSet: DokkaSourceSet, context: DokkaContext): DModule { + override suspend fun invokeSuspending(sourceSet: DokkaSourceSet, context: DokkaContext): DModule { val (environment, facade) = kotlinAnalysis[sourceSet] val packageFragments = environment.getSourceFiles().asSequence() .map { it.packageFqName } diff --git a/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt b/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt index 15ef24bb..bf7fbe7d 100644 --- a/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt +++ b/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt @@ -27,6 +27,7 @@ import org.jetbrains.dokka.model.properties.PropertyContainer import org.jetbrains.dokka.plugability.DokkaContext import org.jetbrains.dokka.plugability.plugin import org.jetbrains.dokka.plugability.querySingle +import org.jetbrains.dokka.transformers.sources.AsyncSourceToDocumentableTranslator import org.jetbrains.dokka.transformers.sources.SourceToDocumentableTranslator import org.jetbrains.dokka.utilities.DokkaLogger import org.jetbrains.dokka.utilities.parallelForEach @@ -52,11 +53,11 @@ import java.io.File class DefaultPsiToDocumentableTranslator( context: DokkaContext -) : SourceToDocumentableTranslator { +) : AsyncSourceToDocumentableTranslator { private val kotlinAnalysis: KotlinAnalysis = context.plugin().querySingle { kotlinAnalysis } - override suspend fun invoke(sourceSet: DokkaSourceSet, context: DokkaContext): DModule { + override suspend fun invokeSuspending(sourceSet: DokkaSourceSet, context: DokkaContext): DModule { return coroutineScope { fun isFileInSourceRoots(file: File): Boolean = sourceSet.sourceRoots.any { root -> file.startsWith(root) } -- cgit