[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.
Kotlin · Jan 25, 2024 · 547d92c · 547d92c
1 parent 671e856
commit 547d92c
Show file tree

Hide file tree

Showing 4 changed files with 34 additions and 2 deletions.
diff --git a/.../src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/DefaultSamplesTransformer.kt b/.../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
@@ -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 <init> ()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/...a-subprojects/plugin-javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/JavadocPlugin.kt b/...a-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<DokkaBase>() }
     private val kotinAsJavaPlugin: KotlinAsJavaPlugin by lazy { plugin<KotlinAsJavaPlugin>() }
+    // defaultSamplesTransformer knows nothing about Javadoc's content model
+    public override val extensionsSuppressed: List<Extension<*, *, *>> by lazy { listOf(dokkaBasePlugin.defaultSamplesTransformer) }
 
     public val locationProviderFactory: ExtensionPoint<LocationProviderFactory> by lazy { dokkaBasePlugin.locationProviderFactory }
     public val javadocPreprocessors: ExtensionPoint<PageTransformer> by extensionPoint<PageTransformer>()

diff --git a/...in-javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocClasslikeTemplateMapTest.kt b/...in-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<JavadocClasslikePageNode>().first{ it.name == "Test" }.templateMap
+            assertEquals("Test", map["name"])
+            assertEquals("<p>some doc</p>", map["classlikeDocumentation"])
+        }
+    }
+
     @Test
     fun `single function`() {
         dualTestTemplateMapInline(