From 86f9559ebd40a07e996df49464fc9101dd21d3bc Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Mon, 26 Sep 2022 18:47:01 +0200 Subject: Add documentation for synthetic Enum `values()` and `valueOf()` functions (#2650) --- .../psi/DefaultPsiToDocumentableTranslator.kt | 15 +++++---- .../psi/SynheticElementDocumentationProvider.kt | 39 ++++++++++++++++++++++ .../translators/psi/parsers/JavadocParser.kt | 5 ++- 3 files changed, 50 insertions(+), 9 deletions(-) create mode 100644 plugins/base/src/main/kotlin/translators/psi/SynheticElementDocumentationProvider.kt (limited to 'plugins/base/src/main/kotlin/translators/psi') diff --git a/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt b/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt index 58524479..574fb2e8 100644 --- a/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt +++ b/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt @@ -8,8 +8,6 @@ import com.intellij.lang.jvm.annotation.JvmAnnotationEnumFieldValue import com.intellij.lang.jvm.types.JvmReferenceType import com.intellij.openapi.vfs.VirtualFileManager import com.intellij.psi.* -import com.intellij.psi.impl.source.PsiClassReferenceType -import com.intellij.psi.impl.source.PsiImmediateClassType import kotlinx.coroutines.async import kotlinx.coroutines.coroutineScope import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet @@ -99,8 +97,8 @@ class DefaultPsiToDocumentableTranslator( facade: DokkaResolutionFacade, private val logger: DokkaLogger ) { - - private val javadocParser: JavaDocumentationParser = JavadocParser(logger, facade) + private val javadocParser = JavadocParser(logger, facade) + private val syntheticDocProvider = SyntheticElementDocumentationProvider(javadocParser, facade) private val cachedBounds = hashMapOf() @@ -404,7 +402,7 @@ class DefaultPsiToDocumentableTranslator( val dri = parentDRI?.let { dri -> DRI.from(psi).copy(packageName = dri.packageName, classNames = dri.classNames) } ?: DRI.from(psi) - val docs = javadocParser.parseDocumentation(psi) + val docs = psi.getDocumentation() return DFunction( dri = dri, name = psi.name, @@ -452,8 +450,13 @@ class DefaultPsiToDocumentableTranslator( ) } + private fun PsiMethod.getDocumentation(): DocumentationNode = + this.takeIf { it is SyntheticElement }?.let { syntheticDocProvider.getDocumentation(it) } + ?: javadocParser.parseDocumentation(this) + private fun PsiMethod.isObvious(inheritedFrom: DRI? = null): Boolean { - return this is SyntheticElement || inheritedFrom?.isObvious() == true + return (this is SyntheticElement && !syntheticDocProvider.isDocumented(this)) + || inheritedFrom?.isObvious() == true } private fun DRI.isObvious(): Boolean { diff --git a/plugins/base/src/main/kotlin/translators/psi/SynheticElementDocumentationProvider.kt b/plugins/base/src/main/kotlin/translators/psi/SynheticElementDocumentationProvider.kt new file mode 100644 index 00000000..376c0940 --- /dev/null +++ b/plugins/base/src/main/kotlin/translators/psi/SynheticElementDocumentationProvider.kt @@ -0,0 +1,39 @@ +package org.jetbrains.dokka.base.translators.psi + +import com.intellij.psi.* +import com.intellij.psi.javadoc.PsiDocComment +import org.jetbrains.dokka.analysis.DokkaResolutionFacade +import org.jetbrains.dokka.base.translators.psi.parsers.JavadocParser +import org.jetbrains.dokka.model.doc.DocumentationNode + +private const val ENUM_VALUEOF_TEMPLATE_PATH = "/dokka/docs/javadoc/EnumValueOf.java.template" +private const val ENUM_VALUES_TEMPLATE_PATH = "/dokka/docs/javadoc/EnumValues.java.template" + +internal class SyntheticElementDocumentationProvider( + private val javadocParser: JavadocParser, + private val resolutionFacade: DokkaResolutionFacade +) { + fun isDocumented(psiElement: PsiElement): Boolean = psiElement is PsiMethod + && (psiElement.isSyntheticEnumValuesMethod() || psiElement.isSyntheticEnumValueOfMethod()) + + fun getDocumentation(psiElement: PsiElement): DocumentationNode? { + val psiMethod = psiElement as? PsiMethod ?: return null + val templatePath = when { + psiMethod.isSyntheticEnumValuesMethod() -> ENUM_VALUES_TEMPLATE_PATH + psiMethod.isSyntheticEnumValueOfMethod() -> ENUM_VALUEOF_TEMPLATE_PATH + else -> return null + } + val docComment = loadSyntheticDoc(templatePath) ?: return null + return javadocParser.parseDocComment(docComment, psiElement) + } + + private fun loadSyntheticDoc(path: String): PsiDocComment? { + val text = javaClass.getResource(path)?.readText() ?: return null + return JavaPsiFacade.getElementFactory(resolutionFacade.project).createDocCommentFromText(text) + } +} + +private fun PsiMethod.isSyntheticEnumValuesMethod() = this.isSyntheticEnumFunction() && this.name == "values" +private fun PsiMethod.isSyntheticEnumValueOfMethod() = this.isSyntheticEnumFunction() && this.name == "valueOf" +private fun PsiMethod.isSyntheticEnumFunction() = this is SyntheticElement && this.containingClass?.isEnum == true + diff --git a/plugins/base/src/main/kotlin/translators/psi/parsers/JavadocParser.kt b/plugins/base/src/main/kotlin/translators/psi/parsers/JavadocParser.kt index 076d43a2..6a39652a 100644 --- a/plugins/base/src/main/kotlin/translators/psi/parsers/JavadocParser.kt +++ b/plugins/base/src/main/kotlin/translators/psi/parsers/JavadocParser.kt @@ -50,14 +50,13 @@ class JavadocParser( override fun parseDocumentation(element: PsiNamedElement): DocumentationNode { return when(val comment = findClosestDocComment(element, logger)){ - is JavaDocComment -> parseDocumentation(comment, element) + is JavaDocComment -> parseDocComment(comment.comment, element) is KotlinDocComment -> parseDocumentation(comment) else -> DocumentationNode(emptyList()) } } - private fun parseDocumentation(element: JavaDocComment, context: PsiNamedElement): DocumentationNode { - val docComment = element.comment + internal fun parseDocComment(docComment: PsiDocComment, context: PsiNamedElement): DocumentationNode { val nodes = listOfNotNull(docComment.getDescription()) + docComment.tags.mapNotNull { tag -> parseDocTag(tag, docComment, context) } -- cgit