From 610b5520b02ce8275462793e176406d1fb37861c Mon Sep 17 00:00:00 2001 From: Vadim Mishenev Date: Wed, 22 Nov 2023 17:14:14 +0300 Subject: Do not find javadoc for non-JVM source set (#3346) * Add test * Do not find javadoc for non-JVM source set * [K2] Add javadoc parser for external documentable Provider --- .../DefaultDescriptorToDocumentableTranslator.kt | 39 ++++++++++++-------- .../SymbolExternalDocumentablesProvider.kt | 13 ++++++- .../DefaultSymbolToDocumentableTranslator.kt | 5 ++- .../kotlin/model/MultiLanguageInheritanceTest.kt | 43 ++++++++++++++++++++++ 4 files changed, 83 insertions(+), 17 deletions(-) diff --git a/dokka-subprojects/analysis-kotlin-descriptors-compiler/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/descriptors/compiler/translator/DefaultDescriptorToDocumentableTranslator.kt b/dokka-subprojects/analysis-kotlin-descriptors-compiler/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/descriptors/compiler/translator/DefaultDescriptorToDocumentableTranslator.kt index 4d561189..04b2cb20 100644 --- a/dokka-subprojects/analysis-kotlin-descriptors-compiler/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/descriptors/compiler/translator/DefaultDescriptorToDocumentableTranslator.kt +++ b/dokka-subprojects/analysis-kotlin-descriptors-compiler/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/descriptors/compiler/translator/DefaultDescriptorToDocumentableTranslator.kt @@ -9,6 +9,7 @@ import com.intellij.psi.PsiNamedElement import com.intellij.psi.util.PsiLiteralUtil.* import kotlinx.coroutines.* import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet +import org.jetbrains.dokka.Platform import org.jetbrains.dokka.analysis.java.JavaAnalysisPlugin import org.jetbrains.dokka.analysis.java.parsers.JavadocParser import org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin @@ -98,11 +99,13 @@ internal class DefaultDescriptorToDocumentableTranslator( .mapNotNull { analysisContext.resolveSession.getPackageFragment(it) } .toList() - val javadocParser = JavadocParser( - docCommentParsers = context.plugin().query { docCommentParsers }, - docCommentFinder = context.plugin().docCommentFinder - ) - + val javadocParser = + if (sourceSet.analysisPlatform == Platform.jvm) + JavadocParser( + docCommentParsers = context.plugin().query { docCommentParsers }, + docCommentFinder = context.plugin().docCommentFinder + ) + else null return DokkaDescriptorVisitor(sourceSet, kdocFinder, kotlinAnalysis[sourceSet], context.logger, javadocParser).run { packageFragments.parallelMap { @@ -128,10 +131,13 @@ internal class DefaultDescriptorToDocumentableTranslator( override fun translateClassDescriptor(descriptor: ClassDescriptor, sourceSet: DokkaSourceSet): DClasslike { val driInfo = DRI.from(descriptor.parents.first()).withEmptyInfo() - val javadocParser = JavadocParser( - docCommentParsers = context.plugin().query { docCommentParsers }, - docCommentFinder = context.plugin().docCommentFinder - ) + val javadocParser = + if (sourceSet.analysisPlatform == Platform.jvm) + JavadocParser( + docCommentParsers = context.plugin().query { docCommentParsers }, + docCommentFinder = context.plugin().docCommentFinder + ) + else null return newSingleThreadContext("Generating documentable model of classlike").use { coroutineContext -> // see https://github.com/Kotlin/dokka/issues/3151 runBlocking(coroutineContext) { @@ -149,12 +155,15 @@ internal data class DRIWithPlatformInfo( internal fun DRI.withEmptyInfo() = DRIWithPlatformInfo(this, emptyMap()) +/** + * @param javadocParser can be null for non JVM platform + */ private class DokkaDescriptorVisitor( private val sourceSet: DokkaSourceSet, private val kDocFinder: KDocFinder, private val analysisContext: AnalysisContext, private val logger: DokkaLogger, - private val javadocParser: JavadocParser + private val javadocParser: JavadocParser? = null ) { private val syntheticDocProvider = SyntheticDescriptorDocumentationProvider(kDocFinder, sourceSet) @@ -1080,16 +1089,16 @@ private class DokkaDescriptorVisitor( else it } ) - } ?: getJavaDocs())?.takeIf { it.children.isNotEmpty() } + } ?: javadocParser?.getJavaDocs(this))?.takeIf { it.children.isNotEmpty() } } - private fun DeclarationDescriptor.getJavaDocs(): DocumentationNode? { - val overriddenDescriptors = (this as? CallableDescriptor)?.overriddenDescriptors ?: emptyList() - val allDescriptors = overriddenDescriptors + listOf(this) + private fun JavadocParser.getJavaDocs(declarationDescriptor: DeclarationDescriptor): DocumentationNode? { + val overriddenDescriptors = (declarationDescriptor as? CallableDescriptor)?.overriddenDescriptors ?: emptyList() + val allDescriptors = overriddenDescriptors + listOf(declarationDescriptor) return allDescriptors .mapNotNull { it.findPsi() as? PsiNamedElement } .firstOrNull() - ?.let { javadocParser.parseDocumentation(it) } + ?.let { parseDocumentation(it) } } private suspend fun ClassDescriptor.companion(dri: DRIWithPlatformInfo): DObject? = companionObjectDescriptor?.let { diff --git a/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/services/SymbolExternalDocumentablesProvider.kt b/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/services/SymbolExternalDocumentablesProvider.kt index 1473a7da..f68de715 100644 --- a/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/services/SymbolExternalDocumentablesProvider.kt +++ b/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/services/SymbolExternalDocumentablesProvider.kt @@ -5,6 +5,9 @@ package org.jetbrains.dokka.analysis.kotlin.symbols.services import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet +import org.jetbrains.dokka.Platform +import org.jetbrains.dokka.analysis.java.JavaAnalysisPlugin +import org.jetbrains.dokka.analysis.java.parsers.JavadocParser import org.jetbrains.dokka.analysis.kotlin.symbols.plugin.SymbolsAnalysisPlugin import org.jetbrains.dokka.analysis.kotlin.symbols.translators.DokkaSymbolVisitor import org.jetbrains.dokka.analysis.kotlin.symbols.translators.getClassIdFromDRI @@ -17,6 +20,7 @@ import org.jetbrains.dokka.plugability.querySingle import org.jetbrains.kotlin.analysis.api.analyze import org.jetbrains.kotlin.analysis.api.symbols.KtNamedClassOrObjectSymbol import org.jetbrains.dokka.analysis.kotlin.internal.ExternalDocumentablesProvider +import org.jetbrains.dokka.plugability.query internal class SymbolExternalDocumentablesProvider(val context: DokkaContext) : ExternalDocumentablesProvider { private val kotlinAnalysis = context.plugin().querySingle { kotlinAnalysis } @@ -26,7 +30,14 @@ internal class SymbolExternalDocumentablesProvider(val context: DokkaContext) : return analyze(kotlinAnalysis.getModule(sourceSet)) { val symbol = getClassOrObjectSymbolByClassId(classId) as? KtNamedClassOrObjectSymbol?: return@analyze null - val translator = DokkaSymbolVisitor(sourceSet, sourceSet.displayName, kotlinAnalysis, logger = context.logger) + val javadocParser = + if (sourceSet.analysisPlatform == Platform.jvm) + JavadocParser( + docCommentParsers = context.plugin().query { docCommentParsers }, + docCommentFinder = context.plugin().docCommentFinder + ) + else null + val translator = DokkaSymbolVisitor(sourceSet, sourceSet.displayName, kotlinAnalysis, logger = context.logger, javadocParser) val parentDRI = symbol.getContainingSymbol()?.let { getDRIFromSymbol(it) } ?: /* top level */ DRI(dri.packageName) with(translator) { diff --git a/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/translators/DefaultSymbolToDocumentableTranslator.kt b/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/translators/DefaultSymbolToDocumentableTranslator.kt index 298d0182..9a17f831 100644 --- a/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/translators/DefaultSymbolToDocumentableTranslator.kt +++ b/dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/translators/DefaultSymbolToDocumentableTranslator.kt @@ -8,6 +8,7 @@ package org.jetbrains.dokka.analysis.kotlin.symbols.translators import org.jetbrains.dokka.analysis.kotlin.symbols.plugin.* import com.intellij.psi.util.PsiLiteralUtil import org.jetbrains.dokka.DokkaConfiguration +import org.jetbrains.dokka.Platform import org.jetbrains.dokka.analysis.java.JavaAnalysisPlugin import org.jetbrains.dokka.analysis.java.parsers.JavadocParser import org.jetbrains.dokka.analysis.kotlin.symbols.kdoc.getGeneratedKDocDocumentationFrom @@ -65,7 +66,7 @@ internal class DefaultSymbolToDocumentableTranslator(context: DokkaContext) : As moduleName = context.configuration.moduleName, analysisContext = analysisContext, logger = context.logger, - javadocParser = javadocParser + javadocParser = if(sourceSet.analysisPlatform == Platform.jvm) javadocParser else null ).visitModule() } } @@ -79,6 +80,8 @@ internal fun T.wrapWithVariance(variance: org.jetbrains.kotlin.types /** * Maps [KtSymbol] to Documentable model [Documentable] + * + * @param javadocParser can be null for non JVM platform */ internal class DokkaSymbolVisitor( private val sourceSet: DokkaConfiguration.DokkaSourceSet, diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/model/MultiLanguageInheritanceTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/model/MultiLanguageInheritanceTest.kt index 9b646f24..c8a18788 100644 --- a/dokka-subprojects/plugin-base/src/test/kotlin/model/MultiLanguageInheritanceTest.kt +++ b/dokka-subprojects/plugin-base/src/test/kotlin/model/MultiLanguageInheritanceTest.kt @@ -4,6 +4,7 @@ package model +import org.jetbrains.dokka.Platform import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest import org.jetbrains.dokka.links.DRI import org.jetbrains.dokka.links.PointingToDeclaration @@ -26,6 +27,48 @@ class MultiLanguageInheritanceTest : BaseAbstractTest() { } } + @Test + fun `should not try to find javadoc for non JVM source set`() { + // Bug #3209 is actual for Dokka K1 + // Technical note: `KtPropertyAccessor`, i.e. ``, is not KtCallableDeclaration so `findKDoc` returns null + // Meanwhile, `getJavaDocs()` for KtPropertyAccessor tries to unexpectedly parse the KDoc documentation of property, i.e. `withHintType` + + val nonJvmConfiguration = dokkaConfiguration { + suppressObviousFunctions = false + sourceSets { + sourceSet { + analysisPlatform = Platform.common.key + sourceRoots = listOf("src/main/kotlin") + } + } + } + + testInline( + """ + |/src/main/kotlin/sample/Parent.kt + |package sample + | + |/** + | * Sample description from parent + | */ + |interface Parent { + | /** + | * Sample description from parent + | */ + | val withHintType: String + |} + | + |/src/main/kotlin/sample/Child.kt + |package sample + |public class Child : Parent { + | override val withHintType: String + | get() = "" + |} + """.trimIndent(), + nonJvmConfiguration + ) { } + } + @Test fun `from java to kotlin`() { testInline( -- cgit