Add documentation for synthetic Enum `values()` and `valueOf()` functions (#2650)

3 files changed, 50 insertions, 9 deletions

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<String, Bound>()
 
@@ -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)
         }