From 547d92c4b51c8179e5dc21058185bee6257cbd9f Mon Sep 17 00:00:00 2001 From: vmishenev Date: Thu, 25 Jan 2024 23:14:44 +0200 Subject: [PATCH 1/2] [Javadoc] Ignore Kotlin samples This is a laconic solution to avoid an error message (#3466) for Kotlin samples in unstable Javadoc format. There are 2 problems. 1. Javadoc's content model does not contain samples links at all. It should contain something like `samplesSectionContent` in the base plugin. 2. Sample Transformer from the base plugin knows nothing about Javadoc's content model. see `DefaultSamplesTransformer.dfs`, e.g. `JavadocContentGroup` is unavailable from the base plugin. --- .../pages/DefaultSamplesTransformer.kt | 3 +++ .../plugin-javadoc/api/plugin-javadoc.api | 3 ++- .../jetbrains/dokka/javadoc/JavadocPlugin.kt | 4 ++- .../JavadocClasslikeTemplateMapTest.kt | 26 +++++++++++++++++++ 4 files changed, 34 insertions(+), 2 deletions(-) diff --git a/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/DefaultSamplesTransformer.kt b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/DefaultSamplesTransformer.kt index 8c51f04fda..8eea0f6c6d 100644 --- a/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/DefaultSamplesTransformer.kt +++ b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/DefaultSamplesTransformer.kt @@ -19,6 +19,9 @@ import org.jetbrains.dokka.analysis.kotlin.sample.SampleSnippet internal const val KOTLIN_PLAYGROUND_SCRIPT = "https://unpkg.com/kotlin-playground@1/dist/playground.min.js" +/** + * It works ONLY with a content model from the base plugin. + */ internal class DefaultSamplesTransformer(val context: DokkaContext) : PageTransformer { private val sampleAnalysisEnvironment: SampleAnalysisEnvironmentCreator = diff --git a/dokka-subprojects/plugin-javadoc/api/plugin-javadoc.api b/dokka-subprojects/plugin-javadoc/api/plugin-javadoc.api index a6b686d7ae..91cc16766b 100644 --- a/dokka-subprojects/plugin-javadoc/api/plugin-javadoc.api +++ b/dokka-subprojects/plugin-javadoc/api/plugin-javadoc.api @@ -11,12 +11,13 @@ public class org/jetbrains/dokka/javadoc/JavadocPageCreator { public final fun pageForPackage (Lorg/jetbrains/dokka/model/DPackage;)Lorg/jetbrains/dokka/javadoc/pages/JavadocPackagePageNode; } -public final class org/jetbrains/dokka/javadoc/JavadocPlugin : org/jetbrains/dokka/plugability/DokkaPlugin { +public final class org/jetbrains/dokka/javadoc/JavadocPlugin : org/jetbrains/dokka/plugability/DokkaPlugin, org/jetbrains/dokka/plugability/WithUnsafeExtensionSuppression { public fun ()V public final fun getAllClassessPageInstaller ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getDeprecatedPageCreator ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getDocumentableSourceSetFilter ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getDokkaJavadocPlugin ()Lorg/jetbrains/dokka/plugability/Extension; + public fun getExtensionsSuppressed ()Ljava/util/List; public final fun getIndexGenerator ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getJavadocLocationProviderFactory ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getJavadocMultiplatformCheck ()Lorg/jetbrains/dokka/plugability/Extension; diff --git a/dokka-subprojects/plugin-javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPlugin.kt b/dokka-subprojects/plugin-javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPlugin.kt index ec502b6d5f..2ad74130b3 100644 --- a/dokka-subprojects/plugin-javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPlugin.kt +++ b/dokka-subprojects/plugin-javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPlugin.kt @@ -27,10 +27,12 @@ import org.jetbrains.dokka.transformers.documentation.PreMergeDocumentableTransf import org.jetbrains.dokka.transformers.pages.PageTransformer import org.jetbrains.dokka.validity.PreGenerationChecker -public class JavadocPlugin : DokkaPlugin() { +public class JavadocPlugin : DokkaPlugin(), WithUnsafeExtensionSuppression { private val dokkaBasePlugin: DokkaBase by lazy { plugin() } private val kotinAsJavaPlugin: KotlinAsJavaPlugin by lazy { plugin() } + // defaultSamplesTransformer knows nothing about Javadoc's content model + public override val extensionsSuppressed: List> by lazy { listOf(dokkaBasePlugin.defaultSamplesTransformer) } public val locationProviderFactory: ExtensionPoint by lazy { dokkaBasePlugin.locationProviderFactory } public val javadocPreprocessors: ExtensionPoint by extensionPoint() diff --git a/dokka-subprojects/plugin-javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocClasslikeTemplateMapTest.kt b/dokka-subprojects/plugin-javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocClasslikeTemplateMapTest.kt index 616d3a4bc1..0c2eb6666b 100644 --- a/dokka-subprojects/plugin-javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocClasslikeTemplateMapTest.kt +++ b/dokka-subprojects/plugin-javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocClasslikeTemplateMapTest.kt @@ -42,6 +42,32 @@ internal class JavadocClasslikeTemplateMapTest : AbstractJavadocTemplateMapTest( } } + @Test + fun `single class should not render Kotlin sample`() { + dualTestTemplateMapInline( + kotlin = + """ + /src/source0.kt + /** + * some doc + * @sample [sample] + */ + class Test { + } + + fun sample(){ + val a = 0 + } + """ + ) { + assertEquals(0, context.logger.errorsCount) + assertEquals(0, context.logger.warningsCount) + val map = allPagesOfType().first{ it.name == "Test" }.templateMap + assertEquals("Test", map["name"]) + assertEquals("

some doc

", map["classlikeDocumentation"]) + } + } + @Test fun `single function`() { dualTestTemplateMapInline( From f9a332688d654ea8324cbec18881f9569afdc0a4 Mon Sep 17 00:00:00 2001 From: "Vadim.Mishenev" Date: Tue, 30 Jan 2024 21:21:34 +0200 Subject: [PATCH 2/2] Use `emptySampleTransformer` --- .../plugin-javadoc/api/plugin-javadoc.api | 3 +-- .../org/jetbrains/dokka/javadoc/JavadocPlugin.kt | 11 ++++++++--- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/dokka-subprojects/plugin-javadoc/api/plugin-javadoc.api b/dokka-subprojects/plugin-javadoc/api/plugin-javadoc.api index 91cc16766b..a6b686d7ae 100644 --- a/dokka-subprojects/plugin-javadoc/api/plugin-javadoc.api +++ b/dokka-subprojects/plugin-javadoc/api/plugin-javadoc.api @@ -11,13 +11,12 @@ public class org/jetbrains/dokka/javadoc/JavadocPageCreator { public final fun pageForPackage (Lorg/jetbrains/dokka/model/DPackage;)Lorg/jetbrains/dokka/javadoc/pages/JavadocPackagePageNode; } -public final class org/jetbrains/dokka/javadoc/JavadocPlugin : org/jetbrains/dokka/plugability/DokkaPlugin, org/jetbrains/dokka/plugability/WithUnsafeExtensionSuppression { +public final class org/jetbrains/dokka/javadoc/JavadocPlugin : org/jetbrains/dokka/plugability/DokkaPlugin { public fun ()V public final fun getAllClassessPageInstaller ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getDeprecatedPageCreator ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getDocumentableSourceSetFilter ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getDokkaJavadocPlugin ()Lorg/jetbrains/dokka/plugability/Extension; - public fun getExtensionsSuppressed ()Ljava/util/List; public final fun getIndexGenerator ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getJavadocLocationProviderFactory ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getJavadocMultiplatformCheck ()Lorg/jetbrains/dokka/plugability/Extension; diff --git a/dokka-subprojects/plugin-javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPlugin.kt b/dokka-subprojects/plugin-javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPlugin.kt index 2ad74130b3..b23f094de5 100644 --- a/dokka-subprojects/plugin-javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPlugin.kt +++ b/dokka-subprojects/plugin-javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPlugin.kt @@ -27,12 +27,10 @@ import org.jetbrains.dokka.transformers.documentation.PreMergeDocumentableTransf import org.jetbrains.dokka.transformers.pages.PageTransformer import org.jetbrains.dokka.validity.PreGenerationChecker -public class JavadocPlugin : DokkaPlugin(), WithUnsafeExtensionSuppression { +public class JavadocPlugin : DokkaPlugin() { private val dokkaBasePlugin: DokkaBase by lazy { plugin() } private val kotinAsJavaPlugin: KotlinAsJavaPlugin by lazy { plugin() } - // defaultSamplesTransformer knows nothing about Javadoc's content model - public override val extensionsSuppressed: List> by lazy { listOf(dokkaBasePlugin.defaultSamplesTransformer) } public val locationProviderFactory: ExtensionPoint by lazy { dokkaBasePlugin.locationProviderFactory } public val javadocPreprocessors: ExtensionPoint by extensionPoint() @@ -96,6 +94,13 @@ public class JavadocPlugin : DokkaPlugin(), WithUnsafeExtensionSuppression { javadocPreprocessors with DeprecatedPageCreator order { before(rootCreator) } } + // defaultSamplesTransformer knows nothing about Javadoc's content model + internal val emptySampleTransformer: Extension by extending { + CoreExtensions.pageTransformer providing { + PageTransformer { it } + } override dokkaBasePlugin.defaultSamplesTransformer + } + internal val alphaVersionNotifier by extending { CoreExtensions.postActions providing { ctx -> PostAction {