Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Do not find javadoc for non-JVM source set #3346

Merged
merged 5 commits into from
Nov 22, 2023
Merged

Do not find javadoc for non-JVM source set #3346

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
01504b1
Add test
vmishenev Nov 15, 2023
6ce3d13
Do not find javadoc for non-JVM source set
vmishenev Nov 15, 2023
3aae66a
Remove redundant check
vmishenev Nov 21, 2023
9ff4919
Add yet another check
vmishenev Nov 21, 2023
9cbf07a
[K2] Add javadoc parser for external documentable Provider
vmishenev Nov 21, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 19 additions & 10 deletions ...lysis/kotlin/descriptors/compiler/translator/DefaultDescriptorToDocumentableTranslator.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -128,10 +129,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<JavaAnalysisPlugin>().query { docCommentParsers },
docCommentFinder = context.plugin<JavaAnalysisPlugin>().docCommentFinder
)
val javadocParser =
if (sourceSet.analysisPlatform == Platform.jvm)
JavadocParser(
docCommentParsers = context.plugin<JavaAnalysisPlugin>().query { docCommentParsers },
docCommentFinder = context.plugin<JavaAnalysisPlugin>().docCommentFinder
)
else null

return newSingleThreadContext("Generating documentable model of classlike").use { coroutineContext -> // see https://github.com/Kotlin/dokka/issues/3151
runBlocking(coroutineContext) {
Expand All @@ -149,12 +153,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)

Expand Down Expand Up @@ -1080,16 +1087,18 @@ 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? {
if(sourceSet.analysisPlatform != Platform.jvm) return null // javadoc is only on JVM platform
vmishenev marked this conversation as resolved.
Show resolved Hide resolved

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 {
Expand Down
5 changes: 4 additions & 1 deletion ...brains/dokka/analysis/kotlin/symbols/translators/DefaultSymbolToDocumentableTranslator.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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()
}
}
Expand All @@ -79,6 +80,8 @@ internal fun <T : Bound> 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,
Expand Down
43 changes: 43 additions & 0 deletions dokka-subprojects/plugin-base/src/test/kotlin/model/MultiLanguageInheritanceTest.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -26,6 +27,48 @@ class MultiLanguageInheritanceTest : BaseAbstractTest() {
}
}

@Test
fun `should not try to find javadoc for non JVM source set`() {
vmishenev marked this conversation as resolved.
Show resolved Hide resolved
// Bug #3209 is actual for Dokka K1
// Technical note: `KtPropertyAccessor`, i.e. `<get-withHintType>`, 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() = ""
|}
Comment on lines +48 to +66
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like such a common case that I don't know how it didn't backfire before 😨

""".trimIndent(),
nonJvmConfiguration
) { }
}

@Test
fun `from java to kotlin`() {
testInline(
Expand Down
Loading