Multilanguage docs inheritance (#1951)

* Multilanguage docs inheritance

* Add map to store inherit doc entries

9 files changed, 251 insertions, 64 deletions

diff --git a/plugins/base/src/main/kotlin/parsers/MarkdownParser.kt b/plugins/base/src/main/kotlin/parsers/MarkdownParser.kt
index 80a9e508..34dceeea 100644
--- a/plugins/base/src/main/kotlin/parsers/MarkdownParser.kt
+++ b/plugins/base/src/main/kotlin/parsers/MarkdownParser.kt
@@ -504,6 +504,7 @@ open class MarkdownParser(
             kDocTag: KDocTag?,
             externalDri: (String) -> DRI?,
             kdocLocation: String?,
+            parseWithChildren: Boolean = true
         ): DocumentationNode {
             return if (kDocTag == null) {
                 DocumentationNode(emptyList())
@@ -517,7 +518,7 @@ open class MarkdownParser(
                 }
 
                 val allTags =
-                    listOf(kDocTag) + if (kDocTag.canHaveParent()) getAllKDocTags(findParent(kDocTag)) else emptyList()
+                    listOf(kDocTag) + if (kDocTag.canHaveParent() && parseWithChildren) getAllKDocTags(findParent(kDocTag)) else emptyList()
                 DocumentationNode(
                     allTags.map {
                         when (it.knownTag) {
diff --git a/plugins/base/src/main/kotlin/signatures/KotlinSignatureProvider.kt b/plugins/base/src/main/kotlin/signatures/KotlinSignatureProvider.kt
index 4eac9d3f..6446a775 100644
--- a/plugins/base/src/main/kotlin/signatures/KotlinSignatureProvider.kt
+++ b/plugins/base/src/main/kotlin/signatures/KotlinSignatureProvider.kt
@@ -123,7 +123,7 @@ class KotlinSignatureProvider(ctcc: CommentsToContentConverter, logger: DokkaLog
                 text(
                     if (c.modifier[sourceSet] !in ignoredModifiers)
                         when {
-                            c.extra[AdditionalModifiers]?.content?.contains(ExtraModifiers.KotlinOnlyModifiers.Data) == true -> ""
+                            c.extra[AdditionalModifiers]?.content?.get(sourceSet)?.contains(ExtraModifiers.KotlinOnlyModifiers.Data) == true -> ""
                             c.modifier[sourceSet] is JavaModifier.Empty -> "${KotlinModifier.Open.name} "
                             else -> c.modifier[sourceSet]?.name?.let { "$it " } ?: ""
                         }
diff --git a/plugins/base/src/main/kotlin/transformers/documentables/ReportUndocumentedTransformer.kt b/plugins/base/src/main/kotlin/transformers/documentables/ReportUndocumentedTransformer.kt
index a8fabc95..f80cb6df 100644
--- a/plugins/base/src/main/kotlin/transformers/documentables/ReportUndocumentedTransformer.kt
+++ b/plugins/base/src/main/kotlin/transformers/documentables/ReportUndocumentedTransformer.kt
@@ -159,6 +159,6 @@ internal class ReportUndocumentedTransformer : DocumentableTransformer {
         val packageName = documentable.dri.packageName ?: return null
         return dokkaSourceSet.perPackageOptions
             .filter { packageOptions -> Regex(packageOptions.matchingRegex).matches(packageName) }
-            .maxBy { packageOptions -> packageOptions.matchingRegex.length }
+            .maxByOrNull { packageOptions -> packageOptions.matchingRegex.length }
     }
 }
diff --git a/plugins/base/src/main/kotlin/transformers/pages/samples/DefaultSamplesTransformer.kt b/plugins/base/src/main/kotlin/transformers/pages/samples/DefaultSamplesTransformer.kt
index a391b534..cadd3de0 100644
--- a/plugins/base/src/main/kotlin/transformers/pages/samples/DefaultSamplesTransformer.kt
+++ b/plugins/base/src/main/kotlin/transformers/pages/samples/DefaultSamplesTransformer.kt
@@ -13,7 +13,7 @@ class DefaultSamplesTransformer(context: DokkaContext) : SamplesTransformer(cont
     override fun processBody(psiElement: PsiElement): String {
         val text = processSampleBody(psiElement).trim { it == '\n' || it == '\r' }.trimEnd()
         val lines = text.split("\n")
-        val indent = lines.filter(String::isNotBlank).map { it.takeWhile(Char::isWhitespace).count() }.min() ?: 0
+        val indent = lines.filter(String::isNotBlank).map { it.takeWhile(Char::isWhitespace).count() }.minOrNull() ?: 0
         return lines.joinToString("\n") { it.drop(indent) }
     }
 
diff --git a/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt b/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt
index 92ffd9b6..8bb8b527 100644
--- a/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt
+++ b/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt
@@ -1,7 +1,9 @@
 package org.jetbrains.dokka.base.translators.descriptors
 
+import com.intellij.psi.PsiNamedElement
 import kotlinx.coroutines.async
 import kotlinx.coroutines.coroutineScope
+import kotlinx.coroutines.runBlocking
 import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet
 import org.jetbrains.dokka.analysis.DescriptorDocumentableSource
 import org.jetbrains.dokka.analysis.DokkaResolutionFacade
@@ -10,6 +12,7 @@ import org.jetbrains.dokka.analysis.from
 import org.jetbrains.dokka.base.DokkaBase
 import org.jetbrains.dokka.base.parsers.MarkdownParser
 import org.jetbrains.dokka.base.translators.isDirectlyAnException
+import org.jetbrains.dokka.base.translators.psi.parsers.JavadocParser
 import org.jetbrains.dokka.base.translators.unquotedValue
 import org.jetbrains.dokka.links.*
 import org.jetbrains.dokka.links.Callable
@@ -38,6 +41,7 @@ import org.jetbrains.kotlin.descriptors.annotations.AnnotationDescriptor
 import org.jetbrains.kotlin.idea.core.getDirectlyOverriddenDeclarations
 import org.jetbrains.kotlin.idea.kdoc.findKDoc
 import org.jetbrains.kotlin.idea.kdoc.resolveKDocLink
+import org.jetbrains.kotlin.js.resolve.diagnostics.findPsi
 import org.jetbrains.kotlin.load.kotlin.toSourceElement
 import org.jetbrains.kotlin.name.FqName
 import org.jetbrains.kotlin.psi.*
@@ -58,6 +62,7 @@ import org.jetbrains.kotlin.types.*
 import org.jetbrains.kotlin.types.typeUtil.immediateSupertypes
 import org.jetbrains.kotlin.types.typeUtil.isAnyOrNullableAny
 import org.jetbrains.kotlin.utils.addToStdlib.firstIsInstanceOrNull
+import org.jetbrains.kotlin.utils.addToStdlib.firstNotNullResult
 import org.jetbrains.kotlin.utils.addToStdlib.safeAs
 import java.nio.file.Paths
 import org.jetbrains.kotlin.resolve.constants.AnnotationValue as ConstantsAnnotationValue
@@ -110,6 +115,8 @@ private class DokkaDescriptorVisitor(
     private val resolutionFacade: DokkaResolutionFacade,
     private val logger: DokkaLogger
 ) {
+    private val javadocParser = JavadocParser(logger, resolutionFacade)
+
     private fun Collection<DeclarationDescriptor>.filterDescriptorsInSourceSet() = filter {
         it.toSourceElement.containingFile.toString().let { path ->
             path.isNotBlank() && sourceSet.sourceRoots.any { root ->
@@ -848,7 +855,7 @@ private class DokkaDescriptorVisitor(
             org.jetbrains.kotlin.types.Variance.OUT_VARIANCE -> Covariance(this)
         }
 
-    private fun DeclarationDescriptor.getDocumentation() = findKDoc().let {
+    private fun DeclarationDescriptor.getDocumentation() = (findKDoc()?.let {
         MarkdownParser.parseFromKDocTag(
             kDocTag = it,
             externalDri = { link: String ->
@@ -871,7 +878,12 @@ private class DokkaDescriptorVisitor(
                 else it
             }
         )
-    }.takeIf { it.children.isNotEmpty() }
+    } ?: getJavaDocs())?.takeIf { it.children.isNotEmpty() }
+
+    private fun DeclarationDescriptor.getJavaDocs() = (this as? CallableDescriptor)
+        ?.overriddenDescriptors
+        ?.mapNotNull { it.findPsi() as? PsiNamedElement }
+        ?.firstNotNullResult { javadocParser.parseDocumentation(it) }
 
     private suspend fun ClassDescriptor.companion(dri: DRIWithPlatformInfo): DObject? = companionObjectDescriptor?.let {
         objectDescriptor(it, dri)
diff --git a/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt b/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt
index f728c8a7..be7b826b 100644
--- a/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt
+++ b/plugins/base/src/main/kotlin/translators/psi/DefaultPsiToDocumentableTranslator.kt
@@ -12,6 +12,7 @@ import com.intellij.psi.impl.source.PsiImmediateClassType
 import kotlinx.coroutines.async
 import kotlinx.coroutines.coroutineScope
 import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet
+import org.jetbrains.dokka.analysis.DokkaResolutionFacade
 import org.jetbrains.dokka.analysis.KotlinAnalysis
 import org.jetbrains.dokka.analysis.PsiDocumentableSource
 import org.jetbrains.dokka.analysis.from
@@ -46,6 +47,7 @@ import org.jetbrains.kotlin.descriptors.Visibilities
 import org.jetbrains.kotlin.descriptors.java.JavaVisibilities
 import org.jetbrains.kotlin.idea.caches.resolve.util.getJavaClassDescriptor
 import org.jetbrains.kotlin.idea.refactoring.fqName.getKotlinFqName
+import org.jetbrains.kotlin.idea.resolve.ResolutionFacade
 import org.jetbrains.kotlin.load.java.JvmAbi
 import org.jetbrains.kotlin.load.java.propertyNameByGetMethodName
 import org.jetbrains.kotlin.load.java.propertyNamesBySetMethodName
@@ -69,7 +71,7 @@ class DefaultPsiToDocumentableTranslator(
                 sourceSet.sourceRoots.any { root -> file.startsWith(root) }
 
 
-            val (environment, _) = kotlinAnalysis[sourceSet]
+            val (environment, facade) = kotlinAnalysis[sourceSet]
 
             val sourceRoots = environment.configuration.get(CLIConfigurationKeys.CONTENT_ROOTS)
                 ?.filterIsInstance<JavaSourceRoot>()
@@ -88,6 +90,7 @@ class DefaultPsiToDocumentableTranslator(
             val docParser =
                 DokkaPsiParser(
                     sourceSet,
+                    facade,
                     context.logger
                 )
 
@@ -106,10 +109,11 @@ class DefaultPsiToDocumentableTranslator(
 
     class DokkaPsiParser(
         private val sourceSetData: DokkaSourceSet,
+        facade: DokkaResolutionFacade,
         private val logger: DokkaLogger
     ) {
 
-        private val javadocParser: JavaDocumentationParser = JavadocParser(logger)
+        private val javadocParser: JavaDocumentationParser = JavadocParser(logger, facade)
 
         private val cachedBounds = hashMapOf<String, Bound>()
 
@@ -207,6 +211,7 @@ class DefaultPsiToDocumentableTranslator(
                 }
                 parseSupertypes(superTypes)
                 val (regularFunctions, accessors) = splitFunctionsAndAccessors()
+                val overriden = regularFunctions.flatMap { it.findSuperMethods().toList() }
                 val documentation = javadocParser.parseDocumentation(this).toSourceSetDependent()
                 val allFunctions = async {
                     regularFunctions.parallelMapNotNull {
@@ -214,8 +219,7 @@ class DefaultPsiToDocumentableTranslator(
                             it,
                             parentDRI = dri
                         ) else null
-                    } +
-                            superMethods.parallelMap { parseFunction(it.first, inheritedFrom = it.second) }
+                    } + superMethods.filter { it.first !in overriden }.parallelMap { parseFunction(it.first, inheritedFrom = it.second) }
                 }
                 val source = PsiDocumentableSource(this).toSourceSetDependent()
                 val classlikes = async { innerClasses.asIterable().parallelMap { parseClasslike(it, dri) } }
diff --git a/plugins/base/src/main/kotlin/translators/psi/parsers/InheritDocResolver.kt b/plugins/base/src/main/kotlin/translators/psi/parsers/InheritDocResolver.kt
index 21c2c72a..67d0a718 100644
--- a/plugins/base/src/main/kotlin/translators/psi/parsers/InheritDocResolver.kt
+++ b/plugins/base/src/main/kotlin/translators/psi/parsers/InheritDocResolver.kt
@@ -7,6 +7,7 @@ import com.intellij.psi.javadoc.PsiDocComment
 import com.intellij.psi.javadoc.PsiDocTag
 import org.jetbrains.dokka.utilities.DokkaLogger
 import org.jetbrains.kotlin.idea.refactoring.fqName.getKotlinFqName
+import org.jetbrains.kotlin.psi.KtElement
 import org.jetbrains.kotlin.utils.addToStdlib.firstIsInstanceOrNull
 
 internal data class CommentResolutionContext(
@@ -21,21 +22,34 @@ internal class InheritDocResolver(
 ) {
     internal fun resolveFromContext(context: CommentResolutionContext) =
         when (context.tag) {
-            JavadocTag.THROWS, JavadocTag.EXCEPTION -> context.name?.let { name -> resolveThrowsTag(context.tag, context.comment, name) }
-            JavadocTag.PARAM -> context.parameterIndex?.let { paramIndex -> resolveParamTag(context.comment, paramIndex) }
+            JavadocTag.THROWS, JavadocTag.EXCEPTION -> context.name?.let { name ->
+                resolveThrowsTag(
+                    context.tag,
+                    context.comment,
+                    name
+                )
+            }
+            JavadocTag.PARAM -> context.parameterIndex?.let { paramIndex ->
+                resolveParamTag(
+                    context.comment,
+                    paramIndex
+                )
+            }
             JavadocTag.DEPRECATED -> resolveGenericTag(context.comment, JavadocTag.DESCRIPTION)
             JavadocTag.SEE -> emptyList()
             else -> context.tag?.let { tag -> resolveGenericTag(context.comment, tag) }
         }
 
-    private fun resolveGenericTag(currentElement: PsiDocComment, tag: JavadocTag): List<PsiElement> =
+    private fun resolveGenericTag(currentElement: PsiDocComment, tag: JavadocTag) =
         when (val owner = currentElement.owner) {
             is PsiClass -> lowestClassWithTag(owner, tag)
             is PsiMethod -> lowestMethodWithTag(owner, tag)
             else -> null
         }?.tagsByName(tag)?.flatMap {
-            when (it) {
-                is PsiDocTag -> it.contentElementsWithSiblingIfNeeded()
+            when {
+                it is PsiDocumentationContent && it.psiElement is PsiDocTag ->
+                    it.psiElement.contentElementsWithSiblingIfNeeded()
+                        .map { content -> PsiDocumentationContent(content, it.tag) }
                 else -> listOf(it)
             }
         }.orEmpty()
@@ -49,58 +63,70 @@ internal class InheritDocResolver(
         tag: JavadocTag,
         currentElement: PsiDocComment,
         exceptionFqName: String
-    ): List<PsiElement> =
-        (currentElement.owner as? PsiMethod)?.let { method -> lowestMethodsWithTag(method, tag) }
+    ): List<DocumentationContent> {
+        val closestDocs = (currentElement.owner as? PsiMethod)?.let { method -> lowestMethodsWithTag(method, tag) }
             .orEmpty().firstOrNull {
                 findClosestDocComment(it, logger)?.hasTagWithExceptionOfType(tag, exceptionFqName) == true
-            }?.docComment?.tagsByName(tag)?.flatMap {
+            }
+
+        return when (closestDocs?.language?.id) {
+            "kotlin" -> closestDocs.toKdocComment()?.tagsByName(tag, exceptionFqName).orEmpty()
+            else -> closestDocs?.docComment?.tagsByName(tag)?.flatMap {
                 when (it) {
                     is PsiDocTag -> it.contentElementsWithSiblingIfNeeded()
                     else -> listOf(it)
                 }
-            }?.withoutReferenceLink().orEmpty()
+            }?.withoutReferenceLink().orEmpty().map { PsiDocumentationContent(it, tag) }
+        }
+    }
 
     private fun resolveParamTag(
         currentElement: PsiDocComment,
         parameterIndex: Int,
-    ): List<PsiElement> =
+    ): List<DocumentationContent> =
         (currentElement.owner as? PsiMethod)?.let { method -> lowestMethodsWithTag(method, JavadocTag.PARAM) }
             .orEmpty().flatMap {
                 if (parameterIndex >= it.parameterList.parametersCount || parameterIndex < 0) emptyList()
                 else {
                     val closestTag = findClosestDocComment(it, logger)
                     val hasTag = closestTag?.hasTag(JavadocTag.PARAM)
-                    if (hasTag != true) emptyList()
-                    else {
-                        val parameterName = it.parameterList.parameters[parameterIndex].name
-                        closestTag.tagsByName(JavadocTag.PARAM)
-                            .filterIsInstance<PsiDocTag>().map { it.contentElementsWithSiblingIfNeeded() }.firstOrNull {
-                                it.firstOrNull()?.text == parameterName
-                            }.orEmpty()
+                    when {
+                        hasTag != true -> emptyList()
+                        closestTag is JavaDocComment -> resolveJavaParamTag(closestTag, parameterIndex, it)
+                            .withoutReferenceLink().map { PsiDocumentationContent(it, JavadocTag.PARAM) }
+                        closestTag is KotlinDocComment -> resolveKdocTag(closestTag, parameterIndex)
+                        else -> emptyList()
                     }
                 }
-            }.withoutReferenceLink()
+            }
+
+    private fun resolveJavaParamTag(comment: JavaDocComment, parameterIndex: Int, method: PsiMethod) =
+        comment.comment.tagsByName(JavadocTag.PARAM)
+            .filterIsInstance<PsiDocTag>().map { it.contentElementsWithSiblingIfNeeded() }.firstOrNull {
+                it.firstOrNull()?.text == method.parameterList.parameters[parameterIndex].name
+            }.orEmpty()
+
+    private fun resolveKdocTag(comment: KotlinDocComment, parameterIndex: Int): List<DocumentationContent> =
+        listOf(comment.tagsByName(JavadocTag.PARAM)[parameterIndex])
 
     //if we are in psi class javadoc only inherits docs from classes and not from interfaces
-    private fun lowestClassWithTag(baseClass: PsiClass, javadocTag: JavadocTag): PsiDocComment? =
+    private fun lowestClassWithTag(baseClass: PsiClass, javadocTag: JavadocTag): DocComment? =
         baseClass.superClass?.let {
-            findClosestDocComment(it, logger)?.takeIf { tag -> tag.hasTag(javadocTag) } ?:
-            lowestClassWithTag(it, javadocTag)
+            findClosestDocComment(it, logger)?.takeIf { tag -> tag.hasTag(javadocTag) } ?: lowestClassWithTag(
+                it,
+                javadocTag
+            )
         }
 
     private fun lowestMethodWithTag(
         baseMethod: PsiMethod,
         javadocTag: JavadocTag,
-    ): PsiDocComment? =
-        lowestMethodsWithTag(baseMethod, javadocTag).firstOrNull()?.docComment
+    ): DocComment? =
+        lowestMethodsWithTag(baseMethod, javadocTag).firstOrNull()
+            ?.let { it.docComment?.let { JavaDocComment(it) } ?: it.toKdocComment() }
 
     private fun lowestMethodsWithTag(baseMethod: PsiMethod, javadocTag: JavadocTag) =
         baseMethod.findSuperMethods().filter { findClosestDocComment(it, logger)?.hasTag(javadocTag) == true }
 
-    private fun PsiDocComment.hasTagWithExceptionOfType(tag: JavadocTag, exceptionFqName: String): Boolean =
-        hasTag(tag) && tagsByName(tag).firstIsInstanceOrNull<PsiDocTag>()
-            ?.resolveToElement()
-            ?.getKotlinFqName()?.asString() == exceptionFqName
-
     private fun List<PsiElement>.withoutReferenceLink(): List<PsiElement> = drop(1)
 }
\ No newline at end of file
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 dc93568f..53424ef9 100644
--- a/plugins/base/src/main/kotlin/translators/psi/parsers/JavadocParser.kt
+++ b/plugins/base/src/main/kotlin/translators/psi/parsers/JavadocParser.kt
@@ -8,13 +8,15 @@ import com.intellij.psi.impl.source.tree.LazyParseablePsiElement
 import com.intellij.psi.impl.source.tree.LeafPsiElement
 import com.intellij.psi.javadoc.*
 import org.intellij.markdown.MarkdownElementTypes
+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.*
 import org.jetbrains.dokka.model.doc.Deprecated
-import org.jetbrains.dokka.model.doc.Suppress
 import org.jetbrains.dokka.utilities.DokkaLogger
 import org.jetbrains.dokka.utilities.enumValueOrNull
+import org.jetbrains.kotlin.idea.kdoc.resolveKDocLink
 import org.jetbrains.kotlin.idea.refactoring.fqName.getKotlinFqName
 import org.jetbrains.kotlin.idea.util.CommentSaver.Companion.tokenType
 import org.jetbrains.kotlin.psi.psiUtil.getNextSiblingIgnoringWhitespace
@@ -23,24 +25,63 @@ import org.jsoup.Jsoup
 import org.jsoup.nodes.Element
 import org.jsoup.nodes.Node
 import org.jsoup.nodes.TextNode
+import java.util.*
 
 interface JavaDocumentationParser {
     fun parseDocumentation(element: PsiNamedElement): DocumentationNode
 }
 
 class JavadocParser(
-    private val logger: DokkaLogger
+    private val logger: DokkaLogger,
+    private val resolutionFacade: DokkaResolutionFacade,
 ) : JavaDocumentationParser {
     private val inheritDocResolver = InheritDocResolver(logger)
 
+    /**
+     * Cache created to make storing entries from kotlin easier.
+     *
+     * It has to be mutable to allow for adding entries when @inheritDoc resolves to kotlin code,
+     * from which we get a DocTags not descriptors.
+     */
+    private var inheritDocSections: MutableMap<UUID, DocumentationNode> = mutableMapOf()
+
     override fun parseDocumentation(element: PsiNamedElement): DocumentationNode {
-        val docComment = findClosestDocComment(element, logger) ?: return DocumentationNode(emptyList())
+        return when(val comment = findClosestDocComment(element, logger)){
+            is JavaDocComment -> parseDocumentation(comment, element)
+            is KotlinDocComment -> parseDocumentation(comment)
+            else -> DocumentationNode(emptyList())
+        }
+    }
+
+    private fun parseDocumentation(element: JavaDocComment, context: PsiNamedElement): DocumentationNode {
+        val docComment = element.comment
         val nodes = listOfNotNull(docComment.getDescription()) + docComment.tags.mapNotNull { tag ->
-            parseDocTag(tag, docComment, element)
+            parseDocTag(tag, docComment, context)
         }
         return DocumentationNode(nodes)
     }
 
+    private fun parseDocumentation(element: KotlinDocComment, parseWithChildren: Boolean = true): DocumentationNode =
+        MarkdownParser.parseFromKDocTag(
+            kDocTag = element.comment,
+            externalDri = { link: String ->
+                try {
+                    resolveKDocLink(
+                        context = resolutionFacade.resolveSession.bindingContext,
+                        resolutionFacade = resolutionFacade,
+                        fromDescriptor = element.descriptor,
+                        fromSubjectOfTag = null,
+                        qualifiedName = link.split('.')
+                    ).firstOrNull()?.let { DRI.from(it) }
+                } catch (e1: IllegalArgumentException) {
+                    logger.warn("Couldn't resolve link for $link")
+                    null
+                }
+            },
+            kdocLocation = null,
+            parseWithChildren = parseWithChildren
+        )
+
     private fun parseDocTag(tag: PsiDocTag, docComment: PsiDocComment, analysedElement: PsiNamedElement): TagWrapper? =
         enumValueOrNull<JavadocTag>(tag.name)?.let { javadocTag ->
             val resolutionContext = CommentResolutionContext(comment = docComment, tag = javadocTag)
@@ -184,6 +225,17 @@ class JavadocParser(
                 else -> stringifySimpleElement(state, context)
             }
 
+        private fun DocumentationContent.stringify(state: ParserState, context: CommentResolutionContext): ParsingResult =
+            when(this){
+                is PsiDocumentationContent -> psiElement.stringify(state, context)
+                is DescriptorDocumentationContent -> {
+                    val id = UUID.randomUUID()
+                    inheritDocSections[id] = parseDocumentation(KotlinDocComment(element, descriptor), parseWithChildren = false)
+                    ParsingResult(state, """<inheritdoc id="$id"/>""")
+                }
+                else -> throw IllegalStateException("Unrecognised documentation content: $this")
+            }
+
         private fun PsiElement.stringifySimpleElement(
             state: ParserState,
             context: CommentResolutionContext
@@ -303,43 +355,57 @@ class JavadocParser(
             }
         }
 
-        private fun createBlock(element: Element, insidePre: Boolean = false): DocTag? {
+        private fun createBlock(element: Element, insidePre: Boolean = false): List<DocTag> {
             val children = element.childNodes()
-                .mapNotNull { convertHtmlNode(it, insidePre = insidePre || element.tagName() == "pre") }
+                .flatMap { convertHtmlNode(it, insidePre = insidePre || element.tagName() == "pre") }
 
-            fun ifChildrenPresent(operation: () -> DocTag): DocTag? {
-                return if (children.isNotEmpty()) operation() else null
+            fun ifChildrenPresent(operation: () -> DocTag): List<DocTag> {
+                return if (children.isNotEmpty()) listOf(operation()) else emptyList()
             }
             return when (element.tagName()) {
                 "blockquote" -> ifChildrenPresent { BlockQuote(children) }
                 "p" -> ifChildrenPresent { P(children) }
                 "b" -> ifChildrenPresent { B(children) }
                 "strong" -> ifChildrenPresent { Strong(children) }
-                "index" -> Index(children)
+                "index" -> listOf(Index(children))
                 "i" -> ifChildrenPresent { I(children) }
-                "em" -> Em(children)
-                "code" -> ifChildrenPresent { CodeInline(children) }
-                "pre" -> Pre(children)
+                "em" -> listOf(Em(children))
+                "code" -> ifChildrenPresent { if(insidePre) CodeBlock(children) else CodeInline(children) }
+                "pre" -> if(children.size == 1 && children.first() is CodeInline) {
+                    listOf(CodeBlock(children.first().children))
+                } else {
+                    listOf(Pre(children))
+                }
                 "ul" -> ifChildrenPresent { Ul(children) }
                 "ol" -> ifChildrenPresent { Ol(children) }
-                "li" -> Li(children)
-                "a" -> createLink(element, children)
+                "li" -> listOf(Li(children))
+                "a" -> listOf(createLink(element, children))
                 "table" -> ifChildrenPresent { Table(children) }
                 "tr" -> ifChildrenPresent { Tr(children) }
-                "td" -> Td(children)
-                "thead" -> THead(children)
-                "tbody" -> TBody(children)
-                "tfoot" -> TFoot(children)
+                "td" -> listOf(Td(children))
+                "thead" -> listOf(THead(children))
+                "tbody" -> listOf(TBody(children))
+                "tfoot" -> listOf(TFoot(children))
                 "caption" -> ifChildrenPresent { Caption(children) }
-                else -> Text(body = element.ownText())
+                "inheritdoc" -> {
+                    val id = UUID.fromString(element.attr("id"))
+                    val section = inheritDocSections[id]
+                    val parsed = section?.children?.flatMap { it.root.children }.orEmpty()
+                    if(parsed.size == 1 && parsed.first() is P){
+                        parsed.first().children
+                    } else {
+                        parsed
+                    }
+                }
+                else -> listOf(Text(body = element.ownText()))
             }
         }
 
-        private fun convertHtmlNode(node: Node, insidePre: Boolean = false): DocTag? = when (node) {
+        private fun convertHtmlNode(node: Node, insidePre: Boolean = false): List<DocTag> = when (node) {
             is TextNode -> (if (insidePre) node.wholeText else node.text()
-                .takeIf { it.isNotBlank() })?.let { Text(body = it) }
+                .takeIf { it.isNotBlank() })?.let { listOf(Text(body = it)) }.orEmpty()
             is Element -> createBlock(node)
-            else -> null
+            else -> emptyList()
         }
 
         override fun invoke(
@@ -352,7 +418,7 @@ class JavadocParser(
             }.parsedLine?.let {
                 val trimmed = it.trim()
                 val toParse = if (asParagraph) "<p>$trimmed</p>" else trimmed
-                Jsoup.parseBodyFragment(toParse).body().childNodes().mapNotNull { convertHtmlNode(it) }
+                Jsoup.parseBodyFragment(toParse).body().childNodes().flatMap { convertHtmlNode(it) }
             }.orEmpty()
     }
 
diff --git a/plugins/base/src/main/kotlin/translators/psi/parsers/PsiCommentsUtils.kt b/plugins/base/src/main/kotlin/translators/psi/parsers/PsiCommentsUtils.kt
index 798b01db..1771595a 100644
--- a/plugins/base/src/main/kotlin/translators/psi/parsers/PsiCommentsUtils.kt
+++ b/plugins/base/src/main/kotlin/translators/psi/parsers/PsiCommentsUtils.kt
@@ -7,8 +7,73 @@ import org.jetbrains.dokka.analysis.from
 import org.jetbrains.dokka.base.translators.psi.findSuperMethodsOrEmptyArray
 import org.jetbrains.dokka.links.DRI
 import org.jetbrains.dokka.utilities.DokkaLogger
+import org.jetbrains.kotlin.descriptors.DeclarationDescriptor
+import org.jetbrains.kotlin.idea.kdoc.findKDoc
+import org.jetbrains.kotlin.idea.refactoring.fqName.getKotlinFqName
+import org.jetbrains.kotlin.idea.search.usagesSearch.descriptor
+import org.jetbrains.kotlin.kdoc.psi.impl.KDocTag
+import org.jetbrains.kotlin.psi.KtDeclaration
+import org.jetbrains.kotlin.psi.KtElement
+import org.jetbrains.kotlin.resolve.DescriptorToSourceUtils
 import org.jetbrains.kotlin.utils.addToStdlib.firstIsInstanceOrNull
 
+internal interface DocComment {
+    fun hasTag(tag: JavadocTag): Boolean
+    fun hasTagWithExceptionOfType(tag: JavadocTag, exceptionFqName: String): Boolean
+    fun tagsByName(tag: JavadocTag, param: String? = null): List<DocumentationContent>
+}
+
+internal data class JavaDocComment(val comment: PsiDocComment) : DocComment {
+    override fun hasTag(tag: JavadocTag): Boolean = comment.hasTag(tag)
+    override fun hasTagWithExceptionOfType(tag: JavadocTag, exceptionFqName: String): Boolean =
+        comment.hasTag(tag) && comment.tagsByName(tag).firstIsInstanceOrNull<PsiDocTag>()
+            ?.resolveToElement()
+            ?.getKotlinFqName()?.asString() == exceptionFqName
+
+    override fun tagsByName(tag: JavadocTag, param: String?): List<DocumentationContent> =
+        comment.tagsByName(tag).map { PsiDocumentationContent(it, tag) }
+}
+
+internal data class KotlinDocComment(val comment: KDocTag, val descriptor: DeclarationDescriptor) : DocComment {
+    override fun hasTag(tag: JavadocTag): Boolean =
+        when (tag) {
+            JavadocTag.DESCRIPTION -> comment.getContent().isNotEmpty()
+            else -> tagsWithContent.any { it.text.startsWith("@$tag") }
+        }
+
+    override fun hasTagWithExceptionOfType(tag: JavadocTag, exceptionFqName: String): Boolean =
+        tagsWithContent.any { it.hasExceptionWithName(tag, exceptionFqName) }
+
+    override fun tagsByName(tag: JavadocTag, param: String?): List<DocumentationContent> =
+        when (tag) {
+            JavadocTag.DESCRIPTION -> listOf(DescriptorDocumentationContent(descriptor, comment, tag))
+            else -> comment.children.mapNotNull { (it as? KDocTag) }
+                .filter { it.name == "$tag" && param?.let { param -> it.hasExceptionWithName(param) } != false }
+                .map { DescriptorDocumentationContent(descriptor, it, tag) }
+        }
+
+    private val tagsWithContent: List<KDocTag> = comment.children.mapNotNull { (it as? KDocTag) }
+
+    private fun KDocTag.hasExceptionWithName(tag: JavadocTag, exceptionFqName: String) =
+        text.startsWith("@$tag") && hasExceptionWithName(exceptionFqName)
+
+    private fun KDocTag.hasExceptionWithName(exceptionFqName: String) =
+        getSubjectName() == exceptionFqName
+}
+
+internal interface DocumentationContent {
+    val tag: JavadocTag
+}
+
+internal data class PsiDocumentationContent(val psiElement: PsiElement, override val tag: JavadocTag) :
+    DocumentationContent
+
+internal data class DescriptorDocumentationContent(
+    val descriptor: DeclarationDescriptor,
+    val element: KDocTag,
+    override val tag: JavadocTag
+) : DocumentationContent
+
 internal fun PsiDocComment.hasTag(tag: JavadocTag): Boolean =
     when (tag) {
         JavadocTag.DESCRIPTION -> descriptionElements.isNotEmpty()
@@ -21,8 +86,10 @@ internal fun PsiDocComment.tagsByName(tag: JavadocTag): List<PsiElement> =
         else -> findTagsByName(tag.toString()).toList()
     }
 
-internal fun findClosestDocComment(element: PsiNamedElement, logger: DokkaLogger): PsiDocComment? {
-    (element as? PsiDocCommentOwner)?.docComment?.run { return this }
+internal fun findClosestDocComment(element: PsiNamedElement, logger: DokkaLogger): DocComment? {
+    (element as? PsiDocCommentOwner)?.docComment?.run { return JavaDocComment(this) }
+    element.toKdocComment()?.run { return this }
+
     if (element is PsiMethod) {
         val superMethods = element.findSuperMethodsOrEmptyArray(logger)
         if (superMethods.isEmpty()) return null
@@ -51,9 +118,20 @@ internal fun findClosestDocComment(element: PsiNamedElement, logger: DokkaLogger
         return if (indexOfSuperClass >= 0) superMethodDocumentation[indexOfSuperClass]
         else superMethodDocumentation.first()
     }
-    return element.children.firstIsInstanceOrNull<PsiDocComment>()
+    return element.children.firstIsInstanceOrNull<PsiDocComment>()?.let { JavaDocComment(it) }
 }
 
+internal fun PsiNamedElement.toKdocComment(): KotlinDocComment? =
+    (navigationElement as? KtElement)?.findKDoc { DescriptorToSourceUtils.descriptorToDeclaration(it) }
+        ?.run {
+            (this@toKdocComment.navigationElement as? KtDeclaration)?.descriptor?.let {
+                KotlinDocComment(
+                    this,
+                    it
+                )
+            }
+        }
+
 internal fun PsiDocTag.contentElementsWithSiblingIfNeeded(): List<PsiElement> = if (dataElements.isNotEmpty()) {
     listOfNotNull(
         dataElements[0],