Skip to content

Commit

Permalink
[Javadoc] Ignore Kotlin samples (#3473)
Browse files Browse the repository at this point in the history
* [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.

(cherry picked from commit e502b2c)
  • Loading branch information
vmishenev authored and IgnatBeresnev committed Jan 31, 2024
1 parent b8ef2dd commit 9d11031
Show file tree
Hide file tree
Showing 3 changed files with 36 additions and 0 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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 =
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,13 @@ public class JavadocPlugin : DokkaPlugin() {
javadocPreprocessors with DeprecatedPageCreator order { before(rootCreator) }
}

// defaultSamplesTransformer knows nothing about Javadoc's content model
internal val emptySampleTransformer: Extension<PageTransformer, *, *> by extending {
CoreExtensions.pageTransformer providing {
PageTransformer { it }
} override dokkaBasePlugin.defaultSamplesTransformer
}

internal val alphaVersionNotifier by extending {
CoreExtensions.postActions providing { ctx ->
PostAction {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down

0 comments on commit 9d11031

Please sign in to comment.