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

2 files changed, 59 insertions, 3 deletions

diff --git a/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt b/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt
index c52fbd37..e3e1a33e 100644
--- a/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt
+++ b/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt
@@ -136,6 +136,7 @@ private class DokkaDescriptorVisitor(
     private val logger: DokkaLogger
 ) {
     private val javadocParser = JavadocParser(logger, resolutionFacade)
+    private val syntheticDocProvider = SyntheticDescriptorDocumentationProvider(resolutionFacade)
 
     private fun Collection<DeclarationDescriptor>.filterDescriptorsInSourceSet() = filter {
         it.toSourceElement.containingFile.toString().let { path ->
@@ -577,8 +578,7 @@ private class DokkaDescriptorVisitor(
                 sources = actual,
                 visibility = descriptor.visibility.toDokkaVisibility().toSourceSetDependent(),
                 generics = generics.await(),
-                documentation = descriptor.takeIf { it.kind != CallableMemberDescriptor.Kind.SYNTHESIZED }
-                    ?.resolveDescriptorData() ?: emptyMap(),
+                documentation = descriptor.getDocumentation(),
                 modifier = descriptor.modifier().toSourceSetDependent(),
                 type = descriptor.returnType!!.toBound(),
                 sourceSets = setOf(sourceSet),
@@ -594,6 +594,15 @@ private class DokkaDescriptorVisitor(
         }
     }
 
+    private fun FunctionDescriptor.getDocumentation(): SourceSetDependent<DocumentationNode> {
+        val isSynthesized = this.kind == CallableMemberDescriptor.Kind.SYNTHESIZED
+        return if (isSynthesized) {
+            syntheticDocProvider.getDocumentation(this)?.toSourceSetDependent() ?: emptyMap()
+        } else {
+            this.resolveDescriptorData()
+        }
+    }
+
     /**
      * `createDRI` returns the DRI of the exact element and potential DRI of an element that is overriding it
      * (It can be also FAKE_OVERRIDE which is in fact just inheritance of the symbol)
@@ -609,7 +618,7 @@ private class DokkaDescriptorVisitor(
 
     private fun FunctionDescriptor.isObvious(): Boolean {
         return kind == CallableMemberDescriptor.Kind.FAKE_OVERRIDE
-                || kind == CallableMemberDescriptor.Kind.SYNTHESIZED
+                || (kind == CallableMemberDescriptor.Kind.SYNTHESIZED && !syntheticDocProvider.isDocumented(this))
                 || containingDeclaration.fqNameOrNull()?.isObvious() == true
     }
 
diff --git a/plugins/base/src/main/kotlin/translators/descriptors/SyntheticDescriptorDocumentationProvider.kt b/plugins/base/src/main/kotlin/translators/descriptors/SyntheticDescriptorDocumentationProvider.kt
new file mode 100644
index 00000000..c96b888a
--- /dev/null
+++ b/plugins/base/src/main/kotlin/translators/descriptors/SyntheticDescriptorDocumentationProvider.kt
@@ -0,0 +1,47 @@
+package org.jetbrains.dokka.base.translators.descriptors
+
+import org.jetbrains.dokka.analysis.DokkaResolutionFacade
+import org.jetbrains.dokka.analysis.from
+import org.jetbrains.dokka.base.parsers.MarkdownParser
+import org.jetbrains.dokka.links.DRI
+import org.jetbrains.dokka.model.doc.DocumentationNode
+import org.jetbrains.kotlin.descriptors.DeclarationDescriptor
+import org.jetbrains.kotlin.descriptors.FunctionDescriptor
+import org.jetbrains.kotlin.idea.kdoc.resolveKDocLink
+import org.jetbrains.kotlin.resolve.DescriptorFactory
+
+private const val ENUM_VALUEOF_TEMPLATE_PATH = "/dokka/docs/kdoc/EnumValueOf.kt.template"
+private const val ENUM_VALUES_TEMPLATE_PATH = "/dokka/docs/kdoc/EnumValues.kt.template"
+
+ internal class SyntheticDescriptorDocumentationProvider(
+    private val resolutionFacade: DokkaResolutionFacade
+) {
+    fun isDocumented(descriptor: DeclarationDescriptor): Boolean = descriptor is FunctionDescriptor
+            && (DescriptorFactory.isEnumValuesMethod(descriptor) || DescriptorFactory.isEnumValueOfMethod(descriptor))
+
+    fun getDocumentation(descriptor: DeclarationDescriptor): DocumentationNode? {
+        val function = descriptor as? FunctionDescriptor ?: return null
+        return when {
+            DescriptorFactory.isEnumValuesMethod(function) -> loadTemplate(descriptor, ENUM_VALUES_TEMPLATE_PATH)
+            DescriptorFactory.isEnumValueOfMethod(function) -> loadTemplate(descriptor, ENUM_VALUEOF_TEMPLATE_PATH)
+            else -> null
+        }
+    }
+
+    private fun loadTemplate(descriptor: DeclarationDescriptor, filePath: String): DocumentationNode? {
+        val kdoc = loadContent(filePath) ?: return null
+        val parser = MarkdownParser({ link -> resolveLink(descriptor, link)}, filePath)
+        return parser.parse(kdoc)
+    }
+
+    private fun loadContent(filePath: String): String? = javaClass.getResource(filePath)?.readText()
+
+    private fun resolveLink(descriptor: DeclarationDescriptor, link: String): DRI? =
+        resolveKDocLink(
+            resolutionFacade.resolveSession.bindingContext,
+            resolutionFacade,
+            descriptor,
+            null,
+            link.split('.')
+        ).firstOrNull()?.let { DRI.from(it) }
+}